Export (0) Print
Expand All

Creating a Simple Plug-in

banner art

[Applies to: Microsoft Dynamics CRM 4.0]

This walkthrough demonstrates how to create a plug-in for a Microsoft Dynamics CRM 4.0 server and register it using the Plug-in Registration Tool. When you run the sample plug-in, it creates a follow up task activity after a new account is created. The task reminds the account owner to follow up with the account customer in 7 days.

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

  • Use Visual Studio to create a new Microsoft Dynamics CRM 4.0 plug-in solution.
  • Add required Web service references to the project.
  • Digitally sign the plug-in.
  • Author a Visual C# plug-in class that will create an activity whenever a new account is created.
  • Use the Plug-in Registration Tool to register the plug-in with the Microsoft Dynamics CRM server.
  • Test the plug-in.

Prerequisites

To complete this walkthrough, you will need the following:

  • Visual Studio 2005 or Visual Studio 2008.
  • A pre-built version of the Plug-in Registration tool.
  • A Microsoft Dynamics CRM SDK installation.
  • Network access to a Microsoft Dynamics CRM 4.0 server.
  • A Microsoft Dynamics CRM system account with either the System Administrator or System Customizer security role, which is also a member of the Deployment Administrators group in Deployment Manager.

You can build the sample directly on the Microsoft Dynamics CRM server assuming all of the prerequisites are met. The Plug-in Registration Tool can be built by following the related walkthrough.

Step 1: Creating a Visual Studio Solution

First you will create a new Visual Studio project and create a Visual C# class file.

To create a Visual Studio solution

  1. In Microsoft Visual Studio, 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 Class Library.
  4. Type a name for your project and then click OK. Use the name AccountCreatePlugin.
  5. In Solution Explorer, rename the Class1.cs file to Plugin.cs.
  6. When you are prompted to rename all references to this file, click Yes.

Step 2: Adding References

You need to add references to the required Microsoft Dynamics CRM assemblies.

To add the necessary assembly references

  1. In Solution Explorer, right-click the References folder and select Add Reference.
  2. Click the Browse tab and navigate to the location of your Microsoft Dynamics CRM DLLs. This may be in the SDK\Bin folder or on your server in the GAC folder. The GAC folder is located on the Microsoft Dynamics CRM server at <crm-root>\Server\i386\GAC.
  3. Select both Microsoft.Crm.Sdk.dll and Microsoft.Crm.SdkTypeProxy.dll and click OK.
  4. In Solution Explorer, right-click the References folder and select Add Reference.
  5. Click the .NET tab, select System.Web.Services, and click OK.

Step 3: Sign your Plug-in

  1. Right-click the AccountCreatePlugin project in Solution Explorer and click Properties.
  2. 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.
  3. Type AccountCreateStrongKey and clear the Protect my key file with a password check box. Click OK.
  4. Save your changes by clicking the Save All button.

Step 4: Write your Plug-in Code

This plug-in will create a new task to send an e-mail to the new customer after an account is created. It also shows you an example of throwing plug-in exceptions to the client, which displays an exception message to the user. The complete project source code can be found at SDK\Walkthroughs\Plugin\CS\AccountCreate.

To add required namespaces

  1. Open the Plugin.cs file and add Microsoft.Crm.Sdk and Microsoft.Crm.SdkTypeProxy to the imported namespaces, as shown in the following code example.
  2. Add a semicolon and the word IPlugin after the class declaration.

Your code should now look like this:

using System;
using System.Collections.Generic;
using System.Text;

using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace Microsoft.Crm.Sdk.Walkthrough
{
    public class AccountCreateHandler : IPlugin
    {
    }
}

To Add the Execute method

The execute method is called when your plug-in is triggered.

  1. Add the Execute method to the CreateAccountHandler class using the following code.
public void Execute(IPluginExecutionContext context)
{
   DynamicEntity entity = null;

   // Check if the input parameters property bag contains a target
   // of the create operation and that target is of type DynamicEntity.
   if (context.InputParameters.Properties.Contains("Target") &&
      context.InputParameters.Properties["Target"] is DynamicEntity)
   {
      // Obtain the target business entity from the input parmameters.
      entity = (DynamicEntity)context.InputParameters.Properties["Target"];

      // Verify that the entity represents an account.
      if (entity.Name != EntityName.account.ToString()) { return; }
   }
   else
   {
      return;
   }

   try
   {
      // Create a task activity to follow up with the account customer in 7 days. 
      DynamicEntity followup = new DynamicEntity();
      followup.Name = EntityName.task.ToString();

      followup.Properties = new PropertyCollection();
      followup.Properties.Add(new StringProperty("subject", "Send e-mail to the new customer."));
      followup.Properties.Add(new StringProperty("description", 
         "Follow up with the customer. Check if there are any new issues that need resolution."));

      followup.Properties.Add(new CrmDateTimeProperty("scheduledstart", 
         CrmTypes.CreateCrmDateTimeFromUniversal(DateTime.Now.AddDays(7))));
      followup.Properties.Add(new CrmDateTimeProperty("scheduledend", 
         CrmTypes.CreateCrmDateTimeFromUniversal(DateTime.Now.AddDays(7))));

      followup.Properties.Add(new StringProperty("category",
         context.PrimaryEntityName));
 
      // Refer to the new account in the task activity.
      if (context.OutputParameters.Properties.Contains("id"))
      {
         Lookup lookup = new Lookup();
         lookup.Value = new Guid(context.OutputParameters.Properties["id"].ToString());
         lookup.type = EntityName.account.ToString();

         followup.Properties.Add(
            new LookupProperty("regardingobjectid", lookup));
      }

      TargetCreateDynamic targetCreate = new TargetCreateDynamic();
      targetCreate.Entity = followup;

      // Create the request object.
      CreateRequest create = new CreateRequest();
      create.Target = targetCreate;

      // Execute the request.
      ICrmService service = context.CreateCrmService(true);
      CreateResponse created = (CreateResponse)service.Execute(create);      
   }
   catch (System.Web.Services.Protocols.SoapException ex)
   {
      throw new InvalidPluginExecutionException(
         "An error occurred in the AccountCreateHandler plug-in.", ex);
   }
}
  1. Compile the project by clicking Build, and then Build Solution.

To deploy the plug-in on your server

If you intend to debug your plug-in, follow these steps to place a copy of the plug-in assembly at the correct location on the Microsoft Dynamics CRM server's disk.

  1. On your development machine, navigate to the bin\Debug folder to find your newly compiled plug-in assembly. This may be in the bin\Release folder depending on your default project settings. Check your project's Build Output path for the correct location.
  2. Copy the compiled plug-in assembly AccountCreatePlugin.dll to the <crmroot>\Server\bin\assembly folder of your Microsoft Dynamics CRM server.

Your plug-in code is now complete.

Step 5: Register your Online Plug-in with the PluginRegistration tool

The plug-in registration tool enables you to register your plug-in with a specific event in Microsoft Dynamics CRM. When that particular event fires, your plug-in will execute. This walkthrough uses database deployment of the plug-in for simplicity.

Note:  There is a security restriction that allows only privileged users to register plug-ins. The system user account under which the plug-in is being registered must exist in the Deployment Administrators group in Deployment Manager. The account must also have either the System Administrator or System Customizer role in Microsoft Dynamics CRM.

To register your plug-in

  1. In Visual Studio, click Tools, and then click CRM Plug-in Registration Tool to run the plug-in registration tool. If you have not added the Plug-in Registration Tool to the Visual Studio Tools menu, then manually run the tool.

    Plug-in Registration Tool

  2. In the Connections panel, enter a descriptive label for the connection. Fill in the other fields as appropriate for your Microsoft Dynamics CRM 4.0 server.
  3. Click Connect. A connection to the server is established and a list of available organizations for the specified system account is displayed.
  4. 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. Clicking any assembly, step, or plug-in displays a list of information about that selected item.

    Assemblies and plug-ins registered with an organization

  5. Select Register, and then select Register New Assembly.
  6. In the Register New Plugin form, click the ellipsis button (…) and navigate to the location of your plug-in assembly.
  7. Select the assembly.

    Note If an exception dialog box is displayed containing a "System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Crm.Sdk'" message, the plug-in registration tool cannot find the Microsoft.Crm.Sdk.dll assembly that it requires. Copy that assembly from the SDK\Bin folder to the folder containing the tool's executable file and try again.

  8. Verify that the Select All and Database options are checked. Click Register Selected Plugins.

    Register New Plugin form

  9. The Registration Log will display the status of the plug-in registration process. Click OK to dismiss the Registered Plugins dialog box.

The assembly and plug-ins are now registered.

To Register a Step for your plug-in

This next procedure registers a step that defines the conditions under which the plug-in is to execute.

  1. Select the plug-in (AccountCreateHandler) in the tree view.
  2. Select Register, and then click Register New Step.
  3. In the Register New Step dialog, enter the information as shown in the figure below and select Register New Step.

    Registering a step

You have just created a synchronous post-event plug-in that will run when an account is created while in online mode. For further information about using the tool, press the F1 key while the tool's window has focus to display online help. You can dismiss the plug-in registration tool at this point.

Note For this SDK release, pressing F1 in the PluginRegistration tool window displays this walkthrough in a browser window. Future SDK releases will include online Help for the PluginRegistration tool.

Test the Plug-in

To test the plug-in you can create an account. This will trigger the plug-in code to run.

  1. Open Internet Explorer, navigate to your Microsoft Dynamics CRM server, click New, and then click Account.
  2. Enter your Account Name and click Save.
  3. After Microsoft Dynamics CRM finishes saving, click the Activities link under Details.
  4. You should see the new activity created for this account with the subject Send e-mail to the new customer.

See Also

Concepts


© 2010 Microsoft Corporation. All rights reserved.


Show:
© 2014 Microsoft