Create custom Unified Service Desk hosted control

You can develop custom Unified Service Desk hosted controls if you have a special requirement that isn’t addressed by the predefined hosted control types. Microsoft Dynamics CRM provides a Visual Studio template for creating a custom Unified Service Desk hosted control. The template provides basic code as comments to help you get started quickly with creating a custom hosted control.

Like the predefined hosted controls, custom Unified Service Desk hosted controls are also derived from the DynamicsBaseHostedControl class.

In this topic, you’ll learn how to create a custom hosted control called My Custom Control with a custom action. The custom hosted control has two Windows Presentation Foundation (WPF) (WPF) controls: a button that calls the Debugger hosted control and a text label that displays the user name when a custom action, MyCustomAction, is called.

In This Section

Prerequisites

Create a custom hosted control

Test your custom hosted control

Prerequisites

• Microsoft .NET Framework 4.5.2

• Unified Service Desk client application; the client application is required for testing the hosted control

• Microsoft Visual Studio 2012 or Visual Studio 2013

• NuGet Package Manager for Visual Studio 2012 or Visual Studio 2013

• Microsoft Dynamics CRM SDK templates for Visual Studio that contains the custom hosted control project template. You can get it in one of the following ways:

  • Download the CRM SDK template from the Visual Studio gallery. Double-click the CRMSDKTemplates.vsix file to install the template in Visual Studio.

  • Download and install the CRM SDK. The templates file, CRMSDKTemplates.vsix, is located in the SDK\Templates folder. Double-click the template file to install it in Visual Studio.

Create a custom hosted control

1. Start Visual Studio, and create a new project.

2. In the New Project dialog box:

   1. From the list of installed templates, expand Visual C#, and select CRM SDK Templates > Unified Service Desk > USD Custom Hosted Control.

   2. Ensure that .NET Framework 4.5.2 is selected.

   3. Specify the name and location of the project, and click OK to create a new project.

   

3. In Solution Explorer, double-click the USDControl.xaml file to bring up the XAML designer.

4. In the designer, add the following controls from the Toolbox:

   • Label: In the Properties pane, set the name of the control to “myLabel.”

   • Button: In the Properties pane, set the name of the control to “myButton,” and the content to “Start Debugger.”

   This is how the controls look in the XAML designer.

   

5. Double-click the button to add code behind the XAML. This will take you to the click event definition of myButton in the USDControl.xaml.cs file. Add the following command.

   private void myButton_Click(object sender, RoutedEventArgs e)
   {
       if (!this.desktopAccess.AppExistsInUI("Debugger"))
       {
           this.desktopAccess.CreateDynamicApplication("Debugger");
       }
       this.FireRequestAction(new Microsoft.Uii.Csr.RequestActionEventArgs("Debugger", "default", null));
   }
   

6. Define a custom action for the hosted control. In the USDControl.xaml.cs file, browse to the override definition of DoAction.

   protected override void DoAction(Microsoft.Uii.Csr.RequestActionEventArgs args)
   

7. Add the following code within the override definition of DoAction to define a custom action called MyCustomAction, which accepts a parameter called username.

   if (args.Action.Equals("MyCustomAction", StringComparison.OrdinalIgnoreCase))
   {
       List<KeyValuePair<string, string>> actionDataList = Utility.SplitLines(args.Data, CurrentContext, localSession);
       string valueIwant = Utility.GetAndRemoveParameter(actionDataList, "username"); // assume there is a myKey=<value> in the data.
   
       if (!string.IsNullOrEmpty(valueIwant))
       {
           this.Dispatcher.Invoke(() => { this.myLabel.Content = valueIwant; });
       }
   }
   

   Tip

   The template provides most of the code as comment within the override definition of DoAction to help you quickly get started with the development. You need to uncomment the required line of code, and replace the placeholder values with your values.

8. Save your project, and build it (Build > Build Solution) to verify that it builds successfully.

Test your custom hosted control

After your project builds successfully, test the custom hosted control. Testing consists of two parts: defining the custom hosted control on the server and then connecting to Unified Service Desk on the server using your client application.

Define the custom hosted control and action on the CRM server

1. Sign in to Microsoft Dynamics CRM.

2. On the nav bar, choose Microsoft Dynamics CRM, and select Settings.

3. Choose Settings > Unified Service Desk > Hosted Controls.

4. Choose NEW, and then specify values in the New Hosted Control screen as shown here.

   

   Note

   Assembly URI is the name of your assembly and the Assembly Type is the name of your assembly (dll) followed by a dot (.) and then the class name in your Visual Studio project. In this example, the name of the assembly is MyCustomControl and name of the class is USDControl, which is the default class name when you create a custom hosted control.

5. Choose Save to create the hosted control.

6. Create the action for the hosted control that you defined in Visual Studio. On the nav bar, choose the down arrow next to your hosted control name, and select UII Actions.

7. Choose Add New UII Action.

8. Type MyCustomAction in the Name field, and choose Save.

You have now configured your custom hosted control and custom action on your CRM server.

Run the Unified Service Desk client to work with custom hosted control

1. Copy the assembly that contains your custom hosted control definition from your Visual Studio project output folder (<ProjectFolder>\bin\debug) to the Unified Service Desk application directory. In this case, you’ll copy the MyCustomControl.dll file to the c:\Program Files\Microsoft Dynamics CRM USD\USD directory.

2. Run Unified Service Desk client to connect to your CRM server.

3. On successful sign in, you’ll see the custom hosted control, My Custom Hosted Control, on your desktop.

   

4. Click Start Debugger to launch the Debugger hosted control.

5. To test the custom action, choose the Debugger tab, and then click the down arrow above the Action Calls tab to display the area where you can test action calls and UII actions.

   

6. Choose the Direct Action tab.

7. From the Hosted Control list, select My Custom Hosted Control, and from the Action list, select MyCustomAction.

8. As per the custom action definition, this action call expects a parameter called username, so add the following value in the Data field: username=Tracie Hamilton.

   

9. Click the Run Direct Action icon (), and then click the My Custom Hosted Control tab. The specified user name is displayed in the label field.

   

See Also

Concepts

USD Hosted Control (Hosted Control)

Other Resources

Hosted control types and action/event reference
Unified Service Desk configuration walkthroughs
Extend Unified Service Desk

Unified Service Desk
Send comments about this topic to Microsoft.
© 2015 Microsoft. All rights reserved.