CRM 3.0 web services: CrmService and MetadataService (2006)

Answer first

CRM 3.0 had two SOAP web services, both under /mscrmservices/2006/ on the CRM web site:

• CrmService (crmservice.asmx): data and business logic, for every entity including custom ones.
• MetadataService (metadataservice.asmx): read-only access to entity, attribute and relationship definitions.

The WSDL is generated on the server and includes that deployment’s customizations. So a project’s web reference is effectively tied to one organization’s schema at the time it was added. It authenticates with Windows credentials, and code acts as another user by setting a CallerId SOAP header.

Source for this page: Microsoft’s CRM 3.0 SDK help and its sample code.

Connecting

• Add a web reference in Visual Studio to http://<server>/mscrmservices/2006/crmservice.asmx, and to metadataservice.asmx if you need metadata. The port is only needed when CRM isn’t on the default web site, for example :5555.
• The reference remembers its server. The generated class defaults its Url to the server the reference was created from. Code that runs anywhere else has to set CrmService.Url, and the SDK’s best practice was to keep that URL in the application’s configuration file.
• Authentication is Windows authentication. The SDK’s examples use System.Net.CredentialCache.DefaultCredentials. Its what’s-new list describes 3.0 as using Active Directory for authentication only. Calling a server in another domain needs explicit credentials for that domain, or a trust between the domains.

Strongly typed, and why that bites

The generated WSDL gives typed classes such as account and contact, including custom entities and attributes as they existed when the reference was made. Problems show up at compile time rather than run time, which is the upside.

The downside is that code only knows entities that were in the WSDL. For anything else, the SDK provides DynamicEntity: an entity name plus an array of properties, with no regenerated WSDL needed. Two limits come with it:

• It only works through Execute, using target classes such as TargetCreateDynamic, TargetRetrieveDynamic and TargetUpdateDynamic. The common methods don’t accept it.
• An entity that doesn’t exist at run time throws an exception.

Callouts receive their record data as serialized DynamicEntity XML too; see CRM 3.0 callouts.

The methods

CrmService has six common methods and one general-purpose one:

Method	What it does
Create	Creates a record
Retrieve	Retrieves one record by ID
RetrieveMultiple	Retrieves records matching a QueryExpression
Update	Updates a record
Delete	Deletes a record
Fetch	Runs a FetchXML query and returns the results as an XML string
Execute	Sends a request message for specialised operations and business logic, returning a response you cast to the matching type

Execute needs the caller to hold the privileges for the entity type in the request, and access rights to the records it names.

Two ways to query

• QueryExpression is a class you build in code, with column sets, conditions, filters and linked entities, and pass to RetrieveMultiple.
• FetchXML is CRM’s own XML query language, passed to Fetch as a string.

Both return only records the calling user can read. Messages convert between the two: FetchXmlToQueryExpression and QueryExpressionToFetchXml.

MetadataService

It reads entity, attribute and relationship definitions, including customizations. Its methods take flags so you can limit how much is returned, and the SDK suggests it for building a client-side cache.

It’s read-only. Entities, attributes and forms can’t be created through it; that has to happen in the customization tools. CRM 4.0 added write methods to the MetadataService.

Impersonation

Unlike the 1.x APIs, 3.0 methods don’t take a user authentication parameter. Code acts on behalf of a user by setting CrmService.CallerIdValue to a CallerId holding that user’s GUID. Rules the SDK sets out:

• The account the code runs under must be in PrivUserGroup, an Active Directory group created when CRM is installed. That account doesn’t need a CRM licence.
• The impersonated user must be a licensed CRM user with privileges for the action.
• Restricted Access Mode must be off on that user’s record, because it restricts what they can do regardless of their roles.
• If the process account isn’t in PrivUserGroup, pass explicit network credentials for an account that is.

Coming from CRM 1.2

The SDK calls the 1.x APIs deprecated and obsolete: the Microsoft.Crm.Platform.Proxy and Microsoft.Crm.Platform.Types assemblies, and the /mscrmservices/*.srf pages. It strongly recommends moving to the 2006 web services. Most 1.2 proxy objects map onto 3.0 entities, for example BizUser to systemuser, BizMerchant to businessunit and CRMAccount to account. The single CRMActivity object became separate entities for e-mail, phone call, task, appointment and the rest.

Some 1.2 code doesn’t carry over:

• activity proxy objects and methods that create activities;
• CRMProcess, since workflows belong in Workflow Manager;
• CRMCustomization, replaced by the InitializeFrom message;
• the old attachment upload pages, replaced by the UploadFromBase64… messages;
• MakePrivate and MakePublic;
• teams owning records, which 3.0 doesn’t allow.

What happened next

Sources: Microsoft’s CRM 4.0 and CRM 2011 SDKs, and Microsoft’s CRM 2013 documentation.

• CRM 4.0 added the 2007 endpoint, /mscrmservices/2007/. It gives each organization its own WSDL and endpoint, with a discovery service to find them.
• The 2006 endpoint kept working in 4.0. Code written for 3.0 didn’t have to change, but two things differ. In a deployment with several organizations its requests go to the default organization, and calls through it skip data validation and default values.
• CRM 2011 kept the 2007 endpoint but didn’t include the 2006 one. Code still on the CRM 3.0 web services had to be upgraded before moving to 2011.
• CRM 2013 ended support for the 2007 endpoint. See the CRM 2013 page, which also notes that Microsoft’s pages disagree about exactly when it went.

Every endpoint from 2006 to today is compared on CrmService to the Web API.