Walkthrough: Create custom hosted control for Unified Service Desk

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2013, Dynamics CRM 2015, Dynamics CRM 2016

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) 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, Visual Studio 2013, or Visual Studio 2015

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

• Microsoft Dynamics 365 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 Dynamics 365 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 Dynamics 365 server

1. Sign in to Microsoft Dynamics 365.

2. On the nav bar, choose Microsoft Dynamics 365, 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 Dynamics 365 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 Dynamics 365 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

USD Hosted Control (Hosted Control)
Hosted control types and action/event reference
Unified Service Desk configuration walkthroughs
Use custom hosted control in Unified Service Desk

Unified Service Desk 2.0

© 2017 Microsoft. All rights reserved. Copyright