In this article by Mahender Pal, the author of the book Microsoft Dynamics CRM 2015 Application Design, we will see how Microsoft Dynamics CRM provides different components that can be highly extended to map our custom business requirements. Although CRM provides a rich set of features that help us execute different business operations without any modification. However, we can still extend its behavior and capabilities with the supported customization.
(For more resources related to this topic, see here.)
The following is the extendibility architecture of CRM 2015, where we can see how different components interact with each other and what are the components that can be extended with the help of CRM APIs:
Extendibility Architecture
Let’s discuss these components one by one and the possible extendibility options for them.
CRM databases
During installation of CRM, two databases, organization and configuration, are created. The organization database is created with the name of organization_MSCRM and the configuration database is created with the name of MSCRM_CONFIG. The organization database contains complete organization-related data stored on different entities. For every entity in CRM, there is a corresponding table with the name of Entityname+Base. Although technically it is possible but any direct data modification in these tables are not supported. Any changes to CRM data should be done by using CRM APIs only.
Adding indexes to the CRM database is supported, you can refer to https://msdn.microsoft.com/en-us/library/gg328350.aspx for more details on supported customizations.
Apart from table, CRM also creates a special view for every entity with the name of Filtered+Entityname. These fields view provide data based on the user security role; so for example, if you are a sales person you will only get data while querying filtered views based on the sales person role. We use filtered views for writing custom reports for CRM. You can refer to more details on filtered views at https://technet.microsoft.com/en-us/library/dn531182.aspx.
Entity relationship diagram can be downloaded from https://msdn.microsoft.com/en-us/library/jj602918.aspx for CRM 2015.
The Platform Layer
Platform layer works as middleware between CRM UI and database, it is responsible for executing inbuilt and custom business logic and moving data back and forth. When we browse a CRM application, the platform layer presents data that is available based on the current user security roles. When we develop and deploy custom component on the top of platform layer.
Process
Process is a way of implementing automation in CRM. We can set up process using process designer and also develop custom assemblies to enhance the capability of workflow designer and include custom steps.
CRM web services
CRM provides Windows Communication Foundation (WCF) based web services, which help us interact with organization data and metadata; so whenever we want to create or modify an entity’s data or want to customize a CRM component’s metadata, we need to utilize these web services. We can also develop our custom web services with the help of CRM web services if required. We will be discussing more about CRM web services in details in a later topic.
Plugins
Plugins are another way of extending the CRM capability. These are .NET assemblies that help us implement our custom business logic in the CRM platform. It helps us to execute our business logic before or after the main platform operation. We can also run our plugin on a transaction that is similar to a SQL transaction, which means if any operation failed, all the changes under transaction will rollback. We can setup asynchronous and synchronous plugins.
Reporting
CRM provides rich reporting capabilities. We have many out of box reports for every module such as sales, marketing, and service. We can also create new reports and customize existing reports in Visual Studio. While working with reports, we always utilize an entity-specific filtered view so that data can be exposed based on the user security role. We should never use a CRM table while writing reports. Custom reports can be developed using out of box report wizard or using Visual Studio. The report wizard helps us create reports by following a couple of screens where we can select an entity and filter the criteria for our report with different rendering and formatting options. We can create two types of reports in Visual Studio SSRS and FetchXML. Custom SSRS reports are supported on CRM on premise deployment whereas CRM online only FetchXML.
You can refer to https://technet.microsoft.com/en-us/library/dn531183.aspx for more details on report development.
Client extensions
We can also extend the CRM application from the Web and Outlook client. We can also develop custom utility tools for it. Sitemap and Command bar editor add-ons are example of such applications. We can modify different CRM components such as entity structure, web resources, business rules, different type of web resources, and other components. CRM web services can be utilized to map custom requirements. We can make navigational changes from CRM clients by modifying Sitemap and Command Bar definition.
Integrated extensions
We can also develop custom extensions in terms of custom utility and middle layer to interact with CRM using APIs. It can be a portal application or any .NET or non .NET utility. CRM SDK comes with many tools that help us to develop these integrated applications. We will be discussing more on custom integration with CRM in a later topic.
Introduction to Microsoft Dynamics CRM SDK
Microsoft Dynamics CRM SDK contains resources that help us develop code for CRM. It includes different CRM APIs and helpful resources such as sample codes (both server side and client side) and a list of tools to facilitate CRM development. It provides a complete documentation of the APIs, methods, and their uses, so if you are a CRM developer, technical consultant, or solution architect, the first thing you need to make sure is to download the latest CRM SDK.
You can download the latest version of CRM SDK from http://www.microsoft.com/en-us/download/details.aspx?id=44567.
The following table talks about the different resources that come with CRM SDK:
|
Name |
Descriptions |
|
Bin |
This folder contains all the assemblies of CRM. |
|
Resources |
This folder contains different resources such as data import maps, default entity ribbon XML definition, and images icons of CRM applications. |
|
SampleCode |
This folder contains all the server side and client side sample code that can help you get started with the CRM development. This folder also contains sample PowerShell commands. |
|
Schemas |
This folder contains XML schemas for CRM entities, command bars, and sitemap. These schemas can be imported in Visual Studio while editing the customization of the .xml file manually. |
|
Solutions |
This folder contains the CRM 2015 solution compatibility chart and one portal solution. |
|
Templates |
This folder contains the visual studio templates that can be used to develop components for a unified service desk and the CRM package deployment. |
|
Tools |
This folder contains tools that are shipped with CRM SDK such as the metadata browser that can used to get CRM entity metadata, plugin registration tool, web resource utility, and others. |
|
Walkthroughts |
This folder contains console and web portal applications. |
|
CrmSdk2015 |
This is the .chm help file. |
|
EntityMetadata |
This file contains entity metadata information. |
|
Message-entity support for plugins |
This is a very important file that will help you understand events available for entities to write custom business logic (plug-ins) |
Learning about CRM assemblies
CRM SDK ships with different assemblies under the bin folder that we can use to write CRM application extension. We can utilize them to interact with CRM metadata and organization data. The following table provides details about the most common CRM assemblies:
|
Name |
Details |
|
Microsoft.Xrm.Sdk.Deployment |
This assembly is used to work with the CRM organization. We can create, update, and delete organization assembly methods. |
|
Microsoft.Xrm.Sdk |
This is very important assembly as it contains the core methods and their details, this assembly is used for every CRM extension. This assembly contains different namespaces for different functionality, for example Query, which contains different classes to query CRM DB; Metadata, which help us interact with the metadata of the CRM application; Discovery, which help us interact with the discover service (we will be discussing the discovery services in a later topic); Messages, which provide classes for all CURD operation requests and responses with metadata classes. |
|
Microsoft.Xrm.Sdk.Workflow |
This assembly helps us extend the CRM workflows’ capability. It contains methods and types which are required for writing custom workflow activity. This assembly contains the activities namespace, which is used by the CRM workflow designer. |
|
Microsoft.Crm.Sdk.Proxy |
This assembly contains all noncore requests and response messages. |
|
Microsoft.Xrm.Tooling |
This is a new assembly added in SDK. This assembly helps to write Windows client applications for CRM |
|
Microsoft.Xrm.Portal |
This assembly provides methods for portal development, which includes security management, cache management, and content management. |
|
Microsoft.Xrm.Client |
This is another assembly that is used in the CRM client application to communicate with CRM from the application. It contains connection classes that we can use to setup the connection using different CRM authentication methods. |
We will be working with these APIs in later topics.
Understanding CRM web services
Microsoft Dynamics CRM provides web service support, which can be used to work with CRM data or metadata. CRM web services are mentioned here.
The deployment service
The deployment service helps us work with organizations. Using this web service, we can create a new organization, delete, or update existing organizations.
The discovery service
Discovery services help us identify correct web service endpoints based on the user. Let’s take an example where we have multiple CRM organizations, and we want to get a list of the organization where current users have access, so we can utilize discovery service to find out unique organization ID, endpoint URL and other details. We will be working with discovery service in a later topic.
The organization service
The organization service is used to work with CRM organization data and metadata. It has the CRUD method and other request and response messages. For example, if we want to create or modify any existing entity record, we can use organization service methods.
The organization data service
The organization data service is a RESTful service that we can use to get data from CRM. We can use this service’s CRUD methods to work with data, but we can’t use this service to work with CRM metadata.
To work with CRM web services, we can use the following two programming models:
- Late bound
- Early bound
Early bound
In early bound classes, we use proxy classes which are generated by CrmSvcUtil.exe. This utility is included in CRM SDK under the SDKBin path. This utility generates classes for every entity available in the CRM system. In this programming model, a schema name is used to refer to an entity and its attributes. This provides intelligence support, so we don’t need to remember the entity and attributes name; as soon as we type the first letter of the entity name, it will display all the entities with that name.
We can use the following syntax to generate proxy class for CRM on premise:
CrmSvcUtil.exe /url:http://<ServerName>/<organizationName>/XRMServices/2011/ Organization.svc /out:proxyfilename.cs /username:<username> /password:<password> /domain:<domainName> /namespace:<outputNamespace> /serviceContextName:<serviceContextName>
The following is the code to generate proxy for CRM online:
CrmSvcUtil.exe
/url:https://orgname.api.crm.dynamics.com/XRMServices/2011/
Organization.svc /out:proxyfilename.cs /username:"[email protected]"
/password:"myp@ssword!
Organization service URLs can be obtained by navigating to Settings | Customization | Developer Resources. We are using CRM online for our demo. In case of CRM online, the organization service URL is dependent on the region where your organization is hosted. You can refer to https://msdn.microsoft.com/en-us/library/gg328127.aspx to get details about different CRM online regions.
We can follow these steps to generate the proxy class for CRM online:
- Navigate to Developer Command Prompt under Visual Studio Tools in your development machine where visual studio is installed.
- Go to the Bin folder under CRM SDK and paste the preceding command:
CrmSvcUtil.exe /url:https://ORGName.api.crm5.dynamics.com/XRMServices/2011/ Organization.svc /out:Xrm.cs /username:"[email protected]" /password:"password"
CrmSVCUtilOnce this file is generated, we can add this file to our visual studio solution.
Late bound
In the late bound programming model, we use the generic Entity object to refer to entities, which means that we can also refer an entity which is not part of the CRM yet. In this programming mode, we need to use logical names to refer to an entity and its attribute. No intelligence support is available during code development in case of late bound. The following is an example of using the Entity class:
Entity AccountObj = new Entity("account");Using Client APIs for a CRM connection
CRM client API helps us connect with CRM easily from .NET applications. It simplifies the developer’s task to setup connection with CRM using a simplified connection string. We can use this connection string to create a organization service object.
The following is the setup to console applications for our demo:
- Connect to Visual Studio and go to File | New | Project.
- Select Visual C# | Console Application and fill CRMConnectiondemo under the Name textbox as shown in the following screenshot:
Console appMake sure you have installed the .NET 4.5.2 and .NET 4.5.2 developer packs before creating sample applications.
- Right-click on References and add the following CRM SDK:
- Microsoft.Xrm.SDK
- Microsoft.Xrm.Client
We also need to add the following .NET assemblies
- System.Runtime.Serialization
- System.Configuration
- Make sure to add the App.config file if not available under project. We need to right-click on Project Name | Add Item and add Application Configuration File as shown here:
app.configfile - We need to add a connection string to our app.config file; we are using CRM online for our demo application, so we will be using following connection string:
<?xml version="1.0" encoding="UTF-8"?> <configuration> <connectionStrings> <add name="OrganizationService" connectionString="Url=https://CRMOnlineServerURL; [email protected]; Password=Password;" /> </connectionStrings> </configuration> - Right-click on Project, select Add Existing File, and browse our file that we generated earlier to add to our console application.
- Now we can add two classes in our application—one for early bound and another for late bound and let’s name them Earlybound.cs and Latebound.cs
You can refer to https://msdn.microsoft.com/en-us/library/jj602970.aspx to connection string for other deployment type, if not using CRM online
After adding the preceding classes, our solution structure should look like this:
Working with organization web services
Whenever we need to interact with CRM SDK, we need to use the CRM web services. Most of the time, we will be working with the Organization service to create and modify data. Organization services contains the following methods to interact with metadata and organization data, we will add these methods to our corresponding Earlybound.cs and Latebound.cs files in our console application.
Create
This method is used to create system or custom entity records. We can use this method when we want to create entity records using CRM SDK, for example, if we need to develop one utility for data import, we can use this method or we want to create lead record in dynamics from a custom website. This methods takes an entity object as a parameter and returns GUID of the record created. The following is an example of creating an account record with early and late bound. With different data types, we are setting some of the basic account entity fields in our code:
- Early bound:
private void CreateAccount() { using (OrganizationService crmService = new OrganizationService("OrganizationService")) { Account accountObject = new Account { Name = "HIMBAP Early Bound Example", Address1_City = "Delhi", CustomerTypeCode = new OptionSetValue(3), DoNotEMail = false, Revenue = new Money(5000), NumberOfEmployees = 50, LastUsedInCampaign = new DateTime(2015, 3, 2) }; crmService.Create(accountObject); } } - Late bound:
private void Create() { using (OrganizationService crmService = new OrganizationService("OrganizationService")) { Entity accountObj = new Entity("account"); //setting string value accountObj["name"] = "HIMBAP"; accountObj["address1_city"] = "Delhi"; accountObj["accountnumber"] = "101"; //setting optionsetvalue accountObj["customertypecode"] = new OptionSetValue(3); //setting boolean accountObj["donotemail"] = false; //setting money accountObj["revenue"] = new Money(5000); //setting entity reference/lookup accountObj["primarycontactid"] = new EntityReference("contact", new Guid("F6954457- 6005-E511-80F4-C4346BADC5F4")); //setting integer accountObj["numberofemployees"] = 50; //Date Time accountObj["lastusedincampaign"] = new DateTime(2015, 05, 13); Guid AccountID = crmService.Create(accountObj); } }
We can also use the create method to create primary and related entity in a single call, for example in the following call, we are creating an account and the related contact record in a single call:
private void CreateRecordwithRelatedEntity()
{
using (OrganizationService crmService = new
OrganizationService("OrganizationService"))
{
Entity accountEntity = new Entity("account");
accountEntity["name"] = "HIMBAP Technology"; Entity
relatedContact = new Entity("contact");
relatedContact["firstname"] = "Vikram";
relatedContact["lastname"] = "Singh";
EntityCollection Related = new EntityCollection();
Related.Entities.Add(relatedContact);
Relationship accountcontactRel = new
Relationship("contact_customer_accounts");
accountEntity.RelatedEntities.Add(accountcontactRel,
Related);
crmService.Create(accountEntity);
}
}
In the preceding code, first we created account entity objects, and then we created an object of related contact entity and added it to entity collection. After that, we added a related entity collection to the primary entity with the entity relationship name; in this case, it is contact_customer_accounts. After that, we passed our account entity object to create a method to create an account and the related contact records. When we will run this code, it will create the account as shown here:
relatedrecord
Update
This method is used to update existing record properties, for example, we might want to change the account city or any other address information. This methods takes the entity object as the parameter, but we need to make sure to update the primary key field to update any record. The following are the examples of updating the account city and setting the state property:
- Early bound:
private void Update() { using (OrganizationService crmService = new OrganizationService("OrganizationService")) { Account accountUpdate = new Account { AccountId = new Guid("85A882EE-A500- E511-80F9-C4346BAC0E7C"), Address1_City = "Lad Bharol", Address1_StateOrProvince = "Himachal Pradesh" }; crmService.Update(accountUpdate); } } - Late bound:
private void Update() { using (OrganizationService crmService = new OrganizationService("OrganizationService")) { Entity accountUpdate = new Entity("account"); accountUpdate["accountid"] = new Guid("85A882EE-A500- E511-80F9-C4346BAC0E7C"); accountUpdate["address1_city"] = " Lad Bharol"; accountUpdate["address1_stateorprovince"] = "Himachal Pradesh"; crmService.Update(accountUpdate); } }
Similarly, to create method, we can also use the update method to update the primary entity and the related entity in a single call as follows:
private void Updateprimaryentitywithrelatedentity()
{
using (OrganizationService crmService = new
OrganizationService("OrganizationService"))
{
Entity accountToUpdate = new Entity("account");
accountToUpdate["name"] = "HIMBAP Technology";
accountToUpdate["websiteurl"] = "www.himbap.com";
accountToUpdate["accountid"] = new Guid("29FC3E74-
B30B-E511-80FC-C4346BAD26CC");//replace it
with actual account id
Entity relatedContact = new Entity("contact");
relatedContact["firstname"] = "Vikram";
relatedContact["lastname"] = "Singh";
relatedContact["jobtitle"] = "Sr Consultant";
relatedContact["contactid"] = new Guid("2AFC3E74-
B30B-E511-80FC-C4346BAD26CC");//replace it
with actual contact id
EntityCollection Related = new EntityCollection();
Related.Entities.Add(relatedContact);
Relationship accountcontactRel = new
Relationship("contact_customer_accounts");
accountToUpdate.RelatedEntities.Add
(accountcontactRel, Related);
crmService.Update(accountToUpdate);
}
}
Retrieve
This method is used to get data from the CRM based on the primary field, which means that this will only return one record at a time. This method has the following three parameter:
- Entity: This is needed to pass the logical name of the entity as fist parameter
- ID: This is needed to pass the primary ID of the record that we want to query
- Columnset: This is needed to specify the fields list that we want to fetch
The following are examples of using the retrieve method
- Early bound:
private void Retrieve() { using (OrganizationService crmService = new OrganizationService("OrganizationService")) { Account retrievedAccount = (Account)crmService.Retrieve (Account.EntityLogicalName, new Guid("7D5E187C-9344-4267- 9EAC-DD32A0AB1A30"), new ColumnSet(new string[] { "name" })); //replace with actual account id } } - Late bound:
private void Retrieve() { using (OrganizationService crmService = new OrganizationService("OrganizationService")) { Entity retrievedAccount = (Entity)crmService.Retrieve("account", new Guid("7D5E187C- 9344-4267-9EAC-DD32A0AB1A30"), new ColumnSet(new string[] { "name"})); }
RetrieveMultiple
The RetrieveMultiple method provides options to define our query object where we can define criteria to fetch records from primary and related entities. This method takes the query object as a parameter and returns the entity collection as a response. The following are examples of using retrievemulitple with the early and late bounds:
- Late Bound:
private void RetrieveMultiple() { using (OrganizationService crmService = new OrganizationService("OrganizationService")) { QueryExpression query = new QueryExpression { EntityName = "account", ColumnSet = new ColumnSet("name", "accountnumber"), Criteria = { FilterOperator = LogicalOperator.Or, Conditions = { new ConditionExpression { AttributeName = "address1_city", Operator = ConditionOperator.Equal, Values={"Delhi"} }, new ConditionExpression { AttributeName="accountnumber", Operator=ConditionOperator.NotNull } } } }; EntityCollection entityCollection = crmService.RetrieveMultiple(query); foreach (Entity result in entityCollection.Entities) { if (result.Contains("name")) { Console.WriteLine("name ->" + result.GetAttributeValue<string>("name").ToString()); } } } - Early Bound:
private void RetrieveMultiple() { using (OrganizationService crmService = new OrganizationService("OrganizationService")) { QueryExpression RetrieveAccountsQuery = new QueryExpression { EntityName = Account.EntityLogicalName, ColumnSet = new ColumnSet("name", "accountnumber"), Criteria = new FilterExpression { Conditions = { new ConditionExpression { AttributeName = "address1_city", Operator = ConditionOperator.Equal, Values = { "Delhi" } } } } }; EntityCollection entityCollection = crmService.RetrieveMultiple(RetrieveAccountsQuery); foreach (Entity result in entityCollection.Entities) { if (result.Contains("name")) { Console.WriteLine("name ->" + result.GetAttributeValue<string> ("name").ToString()); } } } }
Delete
This method is used to delete entity records from the CRM database. This methods takes the entityname and primaryid fields as parameters:
private void Delete()
{
using (OrganizationService crmService = new
OrganizationService("OrganizationService"))
{
crmService.Delete("account", new Guid("85A882EE-A500-E511-
80F9-C4346BAC0E7C"));
}
}
Associate
This method is used to setup a link between two related entities. It has the following parameters:
- Entity Name: This is the logical name of the primary entity
- Entity Id: This is the primary entity records it field.
- Relationship: This is the name of the relationship between two entities
- Related Entities: This is the correction of references
The following is an example of using this method with an early bound:
private void Associate()
{
using (OrganizationService crmService = new
OrganizationService("OrganizationService"))
{
EntityReferenceCollection referenceEntities = new
EntityReferenceCollection();
referenceEntities.Add(new EntityReference("account", new
Guid("38FC3E74-B30B-E511-80FC-C4346BAD26CC")));
// Create an object that defines the relationship between
the contact and account (we want to setup primary contact)
Relationship relationship = new
Relationship("account_primary_contact");
//Associate the contact with the accounts.
crmService.Associate("contact", new Guid("38FC3E74-B30B-
E511-80FC-C4346BAD26CC "), relationship,
referenceEntities);
}
}
Disassociate
This method is the reverse of the associate. It is used to remove a link between two entity records. This method takes the same setup of parameter as associate method takes. The following is an example of a disassociate account and contact record:
private void Disassociate()
{
using (OrganizationService crmService = new
OrganizationService("OrganizationService"))
{
EntityReferenceCollection referenceEntities = new
EntityReferenceCollection();
referenceEntities.Add(new EntityReference("account", new
Guid("38FC3E74-B30B-E511-80FC-C4346BAD26CC ")));
// Create an object that defines the relationship between
the contact and account.
Relationship relationship = new
Relationship("account_primary_contact");
//Disassociate the records.
crmService.Disassociate("contact", new Guid("15FC3E74-
B30B-E511-80FC-C4346BAD26CC "), relationship,
referenceEntities);
}
}
Execute
Apart from the common method that we discussed, the execute method helps to execute requests that is not available as a direct method. This method takes a request as a parameter and returns the response as a result. All the common methods that we used previously can also be used as a request with the execute method. The following is an example of working with metadata and creating a custom event entity using the execute method:
private void Usingmetadata()
{
using (OrganizationService crmService = new
OrganizationService("OrganizationService"))
{
CreateEntityRequest createRequest = new
CreateEntityRequest
{
Entity = new EntityMetadata
{
SchemaName = "him_event",
DisplayName = new Label("Event", 1033),
DisplayCollectionName = new Label("Events",
1033),
Description = new Label("Custom entity demo",
1033),
OwnershipType = OwnershipTypes.UserOwned,
IsActivity = false,
},
PrimaryAttribute = new StringAttributeMetadata
{
SchemaName = "him_eventname",
RequiredLevel = new AttributeRequiredLevelManagedProperty
(AttributeRequiredLevel.None),
MaxLength = 100,
FormatName = StringFormatName.Text,
DisplayName = new Label("Event Name", 1033),
Description = new Label("Primary attribute
demo", 1033)
}
};
crmService.Execute(createRequest);
}
}
In the preceding code, we have utilized the CreateEntityRequest class, which is used to create a custom entity. After executing the preceding code, we can check out the entity under the default solution by navigating to Settings | Customizations | Customize the System.
You can refer to https://msdn.microsoft.com/en-us/library/gg309553.aspx to see other requests that we can use with the execute method.
Testing the console application
After adding the preceding methods, we can test our console application by writing a simple test method where we can call our CRUD methods, for example, in the following example, we have added method in our Earlybound.cs.
public void EarlyboundTesting()
{
Console.WriteLine("Creating Account Record.....");
CreateAccount();
Console.WriteLine("Updating Account Record.....");
Update();
Console.WriteLine("Retriving Account Record.....");
Retrieve();
Console.WriteLine("Deleting Account Record.....");
Delete();
}
After that we can call this method in Main method of Program.cs file like below:
static void Main(string[] args)
{
Earlybound obj = new Earlybound();
Console.WriteLine("Testing Early bound");
obj.EarlyboundTesting();
}
Press F5 to run your console application.
Summary
In this article, you learned about the Microsoft Dynamics CRM 2015 SDK feature. We discussed various options that are available in CRM SDK. You learned about the different CRM APIs and their uses. You learned about different programming models in CRM to work with CRM SDK using different methods of CRM web services, and we created a sample console application.
Resources for Article:
Further resources on this subject:
- Attracting Leads and Building Your List [article]
- PostgreSQL in Action [article]
- Auto updating child records in Process Builder [article]
