Walkthrough: Build a Plug-in That Connects to Microsoft Dynamics CRM Using Developer Extensions
[Applies to: Microsoft Dynamics CRM 2011]
This walkthrough demonstrates how to write a simple Microsoft Dynamics CRM 2011 on-premises plug-in that attaches a note to a new contact.
You can find the sample code that this walkthrough produces in the Walkthroughs\Portals\PluginWalkthrough
folder of the SDK download.
Note
This walkthrough is for a Microsoft Dynamics CRM 2011 on-premises deployment.
In This Topic
Generate Early Bound Types
Set up your plug-in project in Visual Studio
Sign your plug-in project
Create the plug-in that will run your code
Register your plug-in with the Plugin Registration Tool
Generate Early Bound Types
Run the CrmSvcUtil.exe tool, with the Microsoft.Xrm.Client.CodeGeneration extension, to generate your entity classes and service contexts. The following is an example command to create a file called
Xrm.cs
that points at an instance of Microsoft Dynamics CRM. Note that the Microsoft.Xrm.Client.CodeGeneration.dll file must be in the same directory as the CrmSvcUtil.exe file, or in the system global assembly cache, when you run this command.CrmSvcUtil.exe /codeCustomization:"Microsoft.Xrm.Client.CodeGeneration.CodeCustomization, Microsoft.Xrm.Client.CodeGeneration" /out:Xrm\Xrm.cs /url:http://Crm/Contoso/XRMServices/2011/Organization.svc /domain:CONTOSO /username:administrator /password:pass@word1 /namespace:Xrm /serviceContextName:XrmServiceContext
Set up your plug-in project in Visual Studio
Create a new class library project in Microsoft Visual Studio as shown here. This sample uses “Plugin” as the project name.
Add the following references from the
SDK\bin
folder.Microsoft.Xrm.Client.dll
Microsoft.Xrm.Sdk.dll
Add the following .NET references.
Microsoft.IdentityModel.dll
System.Data.Services
System.Data.Services.Client
System.Runtime.Serialization
System.ServiceModel
If you do not have the Microsoft.IdentityModel.dll assembly and are using Microsoft .NET Framework 4.0, you must install Windows Identity Foundation(WIF). However, Windows Identity Foundation is installed by default with .NET Framework 4.5.
Right-click the project in Visual Studio, click Add, and then click Existing Item.
Select the “xrm.cs” file that you created when you generated the early bound types.
Right-click your project again, click Add, and then click New Item.
Select Application Configuration File from the options and then click Add.
Edit the configuration file with your specific connection string. For more information, see Simplified Connection to Microsoft Dynamics CRM.
Sign your plug-in project
Add a strong key to your project
Open the properties pane under your plug-in project.
Create a new strong key file by clicking the Signing tab, select the Sign the assembly check box and select <New…> in the drop down list.
Type a name for your strong key (in this example, it is “PluginWalkthrough”) and clear the ”Protect my key file with a password” check box before clicking OK.
Save your changes.
Create the plug-in that will run your code
This plug-in will run when a contact is created. The following code shows how to create the plug-in.
Right-click your project again, click Add, and then click New Item.
Select Class from the options, type the name “Plugin.cs”, and then click Add.
Add the following code to the Plugins.cs file:
using System; using System.Diagnostics; using System.Linq; using System.ServiceModel; using Microsoft.Xrm.Sdk; using Xrm; public class Plugin: IPlugin { public void Execute(IServiceProvider serviceProvider) { IPluginExecutionContext context = (IPluginExecutionContext) serviceProvider.GetService(typeof(IPluginExecutionContext)); Entity entity; // Check if the input parameters property bag contains a target // of the create operation and that target is of type Entity. if (context.InputParameters.Contains("Target") && context.InputParameters["Target"] is Entity) { // Obtain the target business entity from the input parameters. entity = (Entity)context.InputParameters["Target"]; // Verify that the entity represents a contact. if (entity.LogicalName != "contact") { return; } } else { return; } try { IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService( typeof(IOrganizationServiceFactory)); IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId); var id = (Guid)context.OutputParameters["id"]; AddNoteToContact(service, id); } catch (FaultException<OrganizationServiceFault> ex) { throw new InvalidPluginExecutionException( "An error occurred in the plug-in.", ex); } } private static void AddNoteToContact(IOrganizationService service, Guid id) { using (var crm = new XrmServiceContext(service)) { var contact = crm.ContactSet.Where( c => c.ContactId == id).First(); Debug.Write(contact.FirstName); var note = new Annotation { Subject = "Created with plugin", NoteText = "This Note was created by the example plug-in", ObjectId = contact.ToEntityReference(), ObjectTypeCode = contact.LogicalName }; crm.AddObject(note); crm.SaveChanges(); } } }
Build the solution.
Register your plug-in with the Plugin Registration Tool
Add all dependent assemblies to the global assembly cache on the server. To do this, open your project’s
Debug/bin
folder and copy all *.dll files except for the main PluginWalkthrough.dll file to the global assembly cache on the server.Run the Plug-in Registration tool. Beginning with version 5.0.13 of the SDK, you can find the tool’s executable file in the Bin folder of the SDK download. In previous SDK releases, you had to build the tool from source code provided in the Tools\PluginRegistration folder.
Click Create New Connection.
In the Connections panel, enter a descriptive label for the connection. Fill in the other fields as appropriate for your Microsoft Dynamics CRM server.
Click Connect. A connection to the server is established and a list of available organizations for the specified system account is displayed.
Double-click the desired organization in the connections list. The list of all assemblies, steps, and plug-ins currently registered for the target organization is displayed.
Click Register New Assembly.
In the Register New Plugin dialog box, click the ellipsis button (…) and navigate to the location of your plug-in assembly. Select the assembly and make sure that all plug-ins under it are selected.
Select None for the isolation mode. Note that Developer Extensions for Microsoft Dynamics CRM currently does not support the sandbox isolation mode. Verify that the Database option is selected so that the plug-in will be stored in your organization’s database.
Click Register Selected Plugins.
Click OK.
Expand the assembly and select the plug-in that you just registered. Select Register, and then click Register New Step.
In the Register New Step dialog box, enter the Microsoft Dynamics CRM message that the step will be registered under. In this example, type “Create”. Under Primary Entity, type “contact”. Leave the Pipeline stage set to Post Stage, execution mode to Synchronous, and other options set to default. Click Register New Step.
The registered step appears under the plug-in.
Test the plug-in by creating a new contact in Microsoft Dynamics CRM. After you have saved the entity, a note should be attached.
See Also
Other Resources
Portal Developer Guide for Microsoft Dynamics CRM
Portal Walkthroughs
Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.