Use the XRM tooling common login control in your client applications

  • Article

 

Applies To: Dynamics CRM 2013

The Microsoft Dynamics CRM SDK provides you with a template for Microsoft Visual Studio that enables you to use the common login control in your client applications. The code for CRM authentication, credential storage and retrieval, and diagnostic logging is built into the template so that you can quickly leverage these capabilities in your Windows client applications for CRM. The common login control is an implementation of the Microsoft.Xrm.Tooling.CrmConnectControl, and the control resembles the following image.

XRM Tooling common login control

In This Topic

Prerequisites

Create a WPF application using the common login control template

Add the common login control template to your existing WPF application

Prerequisites

  • Microsoft .NET Framework 4

  • 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 common login control template. You can get it in one of the following ways:

    • Download the Microsoft Dynamics CRM SDK templates from the Visual Studio gallery, and double-click the CRMSDKTemplates.vsix file to install the template in Visual Studio.

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

Create a WPF application using the common login control template

Here is a quick way to create a Windows Presentation Foundation (WPF) application that leverages the common login control and the underlying code for authentication, credential storage and reuse, and default tracing or logging.

  1. Start Microsoft 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.

    2. Select WPF Application for CRM.

    3. Specify the name and location of the project, and click OK.

    WPF Application for CRM template

  3. Add a reference to the Microsoft.Xrm.Tooling.Ui.Resources.dll file to your project. Otherwise, you’ll receive an error while trying to view the login control (LoginWindow\CrmLogin.xaml) in your project’s Solution Explorer pane. The Microsoft.Xrm.Tooling.Ui.Resources.dll file is available in the SDK\bin folder of the CRM SDK package that you downloaded and extracted earlier. To add the reference to this file, right-click References in the Solution Explorer pane, and click Add Reference. In the Reference Manager dialog box, browse to the .dll file, and select it.

  4. To test the project:

    1. Save the project and press F5 or click Debug > Start Debugging to verify if the project compiles successfully. On successful compilation, you’ll see a MainWindow with Login to CRM button. Click the button to display the common login control.

    2. Test the authentication by providing your credentials to connect to CRM, and then click Login. A message displays your CRM connection status.

For a sample that uses the common login control template to connect to CRM and perform various operations, see Sample: Quick start for XRM Tooling API.

Add the common login control template to your existing WPF application

If you already have a WPF client application, you can easily add the common login control template to it to leverage the uniform sign-in experience and the underlying code for CRM authentication, credential storage and reuse, and default tracing or logging. In this case, you must create a control in the user interface of your existing client application to call the common login control, instantiate an instance of the CRM connection object, and then use the connection object to perform various operations in CRM.

  1. Open an existing WPF application project in Visual Studio. For this example, let’s assume that the name of your WPF application project is SampleWPFApp.

  2. Add the common login control template to your project.

    1. In the Solution Explorer pane, right-click the project name, and click Add > New Item.

    2. In the Add New Item dialog box, from the list of installed templates, expand Visual C#, and select CRM SDK Templates. Click CRM Login Form for WPF Applications, and click OK.

      Add the common login control template

  3. A message appears stating that the reference to the Microsoft.Xrm.Tooling.Ui.Resources.dll file couldn’t be added to your project; click OK to close the message. You must manually add the reference to this .dll file; otherwise, you’ll receive an error when you try to view the newly added login control (CrmLoginForm1.xaml) in your project’s Solution Explorer pane.

    The Microsoft.Xrm.Tooling.Ui.Resources.dll file is available in the SDK\bin folder of the CRM SDK package that you downloaded and extracted earlier. To add the reference to this file, right-click References in the Solution Explorer pane, and click Add Reference. In the Reference Manager dialog box, browse to the .dll file, and select it.

  4. After adding the missing reference, verify that the newly added CrmLoginForm1.xaml login control is rendering properly in the designer pane by double-clicking the file in the Solution Explorer pane.

    Verify that the login control renders properly

  5. You must now call the newly added login control from your application. To do this, add a Button control on your MainWindow.xaml file, and set the name and content to btnSignIn and Sign in to CRM respectively.

    Add a control to call the login form

  6. Double-click the button to add code for the click event of the btnSignIn button in the MainWindow.xaml.cs file.

  7. Add the following sample code in the click event of the btnSignIn button to call the CrmLoginForm1 control, and create an instance of the CRM connection object.

    // Establish the Login control.
CRMLoginForm1 ctrl = new CRMLoginForm1();

// Wire event to login response. 
ctrl.ConnectionToCrmCompleted += ctrl_ConnectionToCrmCompleted;

// Show the login control. 
ctrl.ShowDialog();

// Handle the returned CRM connection object.
// On successful connection, display the CRM version and connected org name 
if (ctrl.CrmConnectionMgr != null && ctrl.CrmConnectionMgr.CrmSvc != null && ctrl.CrmConnectionMgr.CrmSvc.IsReady)
{
    MessageBox.Show("Connected to CRM! Version: " + ctrl.CrmConnectionMgr.CrmSvc.ConnectedOrgVersion.ToString() + 
    " Org: " + ctrl.CrmConnectionMgr.CrmSvc.ConnectedOrgUniqueName, "Connection Status");

    // Perform your actions here
}
else
{
    MessageBox.Show("Cannot connect; try again!", "Connection Status");
}

  8. Add the definition of the ctrl_ConnectionToCrmCompleted event below the click event of the button:

    private void ctrl_ConnectionToCrmCompleted(object sender, EventArgs e)
{
    if (sender is CRMLoginForm1)
    {
        this.Dispatcher.Invoke(() =>
        {
            ((CRMLoginForm1)sender).Close();
        });
    }
}

  9. This is how your MainWindow.xaml.cs file appears after adding code from the previous two steps:

    Sample code

  10. To test the project:

    1. Save the project and press F5 or click Debug > Start Debugging to verify if the project compiles successfully. On successful compilation, you will see a MainWindow with the new Sign In to CRM button. Click it to display the common login control.

    2. Test the authentication by providing your credentials to connect to CRM, and then click Login. If successful, a message appears stating the version and the organization name that you are connected to. Click OK to close the message.

      Project test results

    3. If you click Sign In to CRM again, the application prompts you to either choose the saved credentials from the last sign-in activity, or to re-enter the new credentials.

      Stored credentials

See Also

Sample: Quick start for XRM Tooling API
Build Windows client applications using the XRM tools