Walkthrough: Using the Discovery Service with Active Directory Authentication

[Applies to: Microsoft Dynamics CRM 4.0]

This walkthrough demonstrates how to use the Discovery Web service to find the correct CrmService Web service endpoint for your organization. This is for an on-premise installation of Microsoft Dynamics CRM. For more information on the Discovery Web service, see Web Services: CrmDiscoveryService.

During this walkthrough you will learn how to do the following:

• Use Microsoft Visual Studio 2005 to create a console application that uses the Microsoft Dynamics CRM Web services.
• Use Active Directory authentication for interacting with the Microsoft Dynamics CRM Web services.

This walkthrough utilizes Microsoft Visual C# sample code only. However, a Microsoft Visual Basic .NET version of the code can be found at SDK\Walkthroughs\Authentication\VB\ActiveDirectory.

Prerequisites

In order to complete this walkthrough, you will need the following:

• Access to a Microsoft Dynamics CRM 4.0 server.
• A Microsoft Dynamics CRM system account.
• Visual Studio 2005.

Creating a Visual Studio 2005 Solution

You will use a Visual Studio 2005 solution to build your project code.

To create a Visual Studio 2005 solution

1. In Microsoft Visual Studio 2005, on the File menu, point to New, and then click Project to open the New Project dialog box.

2. In the Project types pane, select Visual C#.

3. In the Templates pane, click Console Application.

4. Type a name for your project and then click OK.

While this walkthrough only shows the Visual C# code for the project, a VB.NET version of the code can be found in the SDK\Walkthroughs\Authentication\VB\ActiveDirectory folder.

Adding Web References

You need to add Web references to the required Microsoft Dynamics CRM Web services. By adding these Web references, you are making the Web service proxy namespaces accessible to your project.

To add the CrmDiscoveryService Web service reference

1. In the Solution Explorer window, right-click your project name and choose Add Web Reference.

2. In the Add Web Reference wizard, type the URL for the CrmDiscoveryService Web service in the URL box, using the name and port number for your Microsoft Dynamics CRM server, and then click Go. For example:

3. http://<servername:port>/mscrmservices/2007/AD/CrmDiscoveryService.asmx

4. When the CrmDiscoveryService Web service is found, change the text in the Web reference name box to CrmSdk.Discovery and then click Add Reference.

To add the CrmService Web service reference

1. In the Solution Explorer window, right-click your project name and choose Add Web Reference.

2. In the Add Web Reference wizard, type the URL for the CrmService Web service in the URL box, using the name and port number for your Microsoft Dynamics CRM server, and then click Go. For example:

3. http://<servername:port>/mscrmservices/2007/CrmServiceWsdl.aspx

4. When the CrmService Web service is found, change the text in the Web reference name box to CrmSdk and then click Add Reference.

Note that you can name the Web references any name that you like, but for this example they have been named CrmSdk and CrmSdk.Discovery.

Accessing Microsoft Dynamics CRM Web Services

To access the Microsoft Dynamics CRM Web services and work with business entities, your code typically includes these kinds of program statements:

• Using statements, which provide access to the required namespaces.
• Code that instantiates the CrmDiscoveryService and CrmService Web service proxies.
• Instantiation of Microsoft Dynamics types.
• Invocation of Web service methods.

To include the required .NET namespaces

Add the following lines of code above the namespace statement in your project:

[C#]

 using System.Web.Services.Protocols;
 using System.Xml;                                       
 

To include the required Microsoft Dynamics CRM Web service namespaces

Add the following lines of code after the namespace statement and before the class statement:

// Import the Microsoft Dynamics CRM namespaces.
using CrmSdk;
using CrmSdk.Discovery;
// This class is found in Microsoft.Crm.Sdk.dll. You can add a reference
// to the DLL and remove this class definition if you like. 
public sealed class AuthenticationType
{
	public const int AD = 0;
	public const int Passport = 1;
	public const int Spla = 2;
}

This code also adds an AuthenticationType class that is used later in the sample code.

To add configuration information to your solution

Add the following code after the class statement and before the Main method. This code sets up the necessary variables such as organization name. Be sure to fill in the correct values for the server name, TCP port, and organization of your Microsoft Dynamics CRM installation.

[C#]

// The following configuration data is site specific.
// TODO: Set the name and TCP port of the server hosting Microsoft Dynamics CRM.
static private string _hostname = "localhost";
static private string _port = "80";

// TODO: Set the target organization.
static private string _organization = "AdventureWorksCycle";

#endregion Configuration data

// Expired authentication ticket error code. The error codes can be found in the
// SDK documentation at Server Programming Guide\Programming Reference\Error Codes.
static private string ExpiredAuthTicket = "8004A101";

To add error handling to your solution

Add the following code within the Main method. This code will provide some console output you can use to verify that your program is working.

[C#]

try
{
    Run();
    Console.WriteLine("Authentication was successfull.");
}
catch (System.Exception ex)
{
    Console.WriteLine("The application terminated with an error.");
    Console.WriteLine(ex.Message);

    // Display the details of the inner exception.
    if (ex.InnerException != null)
    {
        Console.WriteLine(ex.InnerException.Message);

        SoapException se = ex.InnerException as SoapException;
        if (se != null)
            Console.WriteLine(se.Detail.InnerText);
    }
}
finally
{
    Console.WriteLine("Press  to exit.");
    Console.ReadLine();
}

Your program will not build because the Run method does not exist. You will create this next.

To add the Run method

This method contains all the code needed to use the Discovery service to obtain the correct URL of the CrmService Web service for your organization. The code then sends a WhoAmI request to the service to verify that the user has been successfully authenticated.

Add the following code after the Main method.

[C#]

public static bool Run()
{
    try
    {
        // STEP 1: Instantiate and configure the CrmDiscoveryService Web service.
        CrmDiscoveryService discoveryService = new CrmDiscoveryService();
        discoveryService.UseDefaultCredentials = true;
        discoveryService.Url = String.Format(
            "http://{0}:{1}/MSCRMServices/2007/{2}/CrmDiscoveryService.asmx",
            _hostname, _port, "AD");

        // STEP 2: Retrieve the organization name and endpoint Url from the
        // CrmDiscoveryService Web service.
        RetrieveOrganizationsRequest orgRequest = 
            new RetrieveOrganizationsRequest();
        RetrieveOrganizationsResponse orgResponse =
            (RetrieveOrganizationsResponse)discoveryService.Execute(orgRequest);

        OrganizationDetail orgInfo = null;

        foreach (OrganizationDetail orgDetail in orgResponse.OrganizationDetails)
        {
            if (orgDetail.OrganizationName.Equals(_organization))
            {
                orgInfo = orgDetail;
                break;
            }
        }

        if (orgInfo == null)
            throw new Exception("The organization name is invalid.");

        // STEP 3: Create and configure an instance of the CrmService Web service.
        CrmAuthenticationToken token = new CrmAuthenticationToken();
        token.AuthenticationType = AuthenticationType.AD;
        token.OrganizationName = orgInfo.OrganizationName;

        CrmService crmService = new CrmService();
        crmService.Url = orgInfo.CrmServiceUrl;
        crmService.CrmAuthenticationTokenValue = token;
        crmService.Credentials = System.Net.CredentialCache.DefaultCredentials;

        // STEP 4: Invoke CrmService Web service methods.
        WhoAmIRequest whoRequest = new WhoAmIRequest();
        WhoAmIResponse whoResponse = (WhoAmIResponse)crmService.Execute(whoRequest);

        return true;
    }

    // Handle any Web service exceptions that might be thrown.
    catch (SoapException ex)
    {
        throw new Exception("An error occurred while attempting to authenticate.", ex);
    }
}

To add the GetErrorCode method

Add the following code, after the Run method, for the GetErrorCode method that extracts a numeric error code from a SoapException stored in anXmlNode or returns an empty string if no error exists.

[C#]

private static string GetErrorCode(XmlNode errorInfo)
{
    XmlNode code = errorInfo.SelectSingleNode("//code");

    if (code != null)
        return code.InnerText;
    else
        return "";
}

Now build and run your solution by pressing F5. If you get any compile errors, you can find the complete code sample in the SDK\Walkthroughs\Authentication\CS|VB\ActiveDirectory folder.