Walkthrough: Create custom hosted control for Unified Service Desk

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

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

  • Visual Studio 2012, Visual Studio 2013, or Visual Studio 2015

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

  • CRM SDK Templates for Visual Studio that contains the custom hosted control project template. Download the CRM SDK Templates from the Visual Studio gallery, and double-click the CRMSDKTemplates.vsix file to install the template 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.6.2 is selected.

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

    Template for creating a custom hosted control

  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.

    XAML designer with custom controls

  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

  1. Sign in to the Common Data Service platform.

  2. On the nav bar, choose Dynamics 365.

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

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

    New custom hosted control

    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 Common Data Service platform 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 Common Data Service platform server.

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

    Custom hosted control

  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.

    Expanded testing area in debugger

  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.

    Test your custom hosted control

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

    My Custom Host Control tab shows username

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