Export (0) Print
Expand All

Creating a Plug-in for Microsoft Dynamics CRM for Outlook that Works Offline

banner art

[Applies to: Microsoft Dynamics CRM 4.0]

This Microsoft Dynamics CRM for Microsoft Office Outlook walkthrough demonstrates how to create a plug-in for online or offline execution on a Microsoft Dynamics CRM 4.0 server. This walkthrough extends the simple AccountCreatePlugin project code that was created in the previous plug-in walkthrough. You are encouraged to complete the walkthrough for the simple plug-in first, because this walkthrough modifies that plug-in's code.

When executed by Microsoft Dynamics CRM, the plug-in developed in this walkthrough creates a follow up task activity when 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:

  • Modify an existing plug-in to add offline capability.
  • Use the Plug-in Registration Tool to register your plug-in with the Microsoft Dynamics CRM server.
  • Test the plug-in in both online and offline modes.

Prerequisites

To complete this walkthrough, you will need the following:

  • Visual Studio 2005, Visual Studio 2008, or Visual C# Express.
  • A pre-built version of the Plug-in Registration tool.
  • Access to the SDK samples\Bin folder.
  • The AccountCreatePlugin project from the Creating a Simple Plug-in walkthrough.
  • Microsoft Office Outlook installed on a computer other than the Microsoft Dynamics CRM server.
  • Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access installed on the computer running Outlook.
  • 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 that 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.

Consult the Microsoft Dynamics CRM Implementation Guide for information on how to install Microsoft Dynamics CRM for Outlook with Offline Access. Microsoft Dynamics CRM for Outlook can be installed on a desktop computer for testing purposes.

Step 1: Modify the AccountCreate Plugin to Support Offline Execution

In this step, you are going to modify the AccountCreatePlugin project sample code to add support for executing the sample plug-in offline. The following code sample shows the complete AccountCreatePlugin source code with the offline support code changes highlighted.

[C#]

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

namespace Microsoft.Crm.Sdk.Walkthrough
{
    /// <summary>
    /// A simple plug-in class that creates a task activity
    /// to follow up with the customer in one week. The plug-in must
    /// be registered to execute after (post-event) an account is created
    /// in Microsoft Dynamics CRM 4 (on-premise).
    /// </summary>
    public class AccountCreateHandler: IPlugin
    {
        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
                // parameters.
                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));

               // Check if the service is offline.
               if (context.IsExecutingInOfflineMode)
               {
                    // When in offline mode, a key must be generated for
                    // each new entity. Perform any other offline work here.
                    Key key = new Key();
                    key.Value = Guid.NewGuid();

                    followup.Properties.Add(new KeyProperty("activityid", key));
               }

               // 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;

               // Create the task on the Microsoft Dynamics CRM server.
               ICrmService service = (ICrmService)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);
            }
        }
    }
}

To add offline support to the AccountCreatePlugin project code, follow these steps:

  1. Make a copy of the SDK\Walkthroughs\AccountCreatePlugin folder. You can modify the copy for this walkthrough. As an alternative, use the solution that you created in the Creating a Simple Plug-in walkthrough.
  2. Double-click the AccountCreatePlugin.sln file to open the solution in Visual Studio.
  3. Modify the Plugin.cs file according to the code changes that are highlighted in the sample code shown above.
  4. Compile the project by clicking Build, and then Build Solution.

A plug-in assembly named AccountCreatePlugin.dll can now be found in the bin/Debug folder of your project.

Step 2: Register your 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.

To register your plug-in

  1. In Visual Studio click Tools, and then click CRM Plug-in Registration Tool.

    Plug-in Registration Tool

  2. Follow the instructions in Step 5 of the Creating a Simple Plug-in walkthrough to register the AccountCreatePlugin.dll assembly and plug-in that have been modified according to the instructions in this walkthrough. Do not follow the "To Register a Step for your plug-in" procedure in that walkthrough. Continue with the step registration procedure in this walkthrough.

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 of the tool.
  2. Select Register, and then click Register New Step.
  3. In the Register New Step dialog box, enter the information as shown in the figure below and select Register New Step.

    Registering an online and offline step

    Note that both the Server and Offline boxes are checked.

You just registered a synchronous post-event plug-in that will run when a new account is created in online or offline mode.

Step 3: Add a Registry Sub-key to the AllowList

An additional security restriction for an offline plug-in requires that a registry key named after the public key token of the plug-in assembly must be added to the system registry.

Determine the plug-in assembly public key token

  1. In the PluginRegistration tool, click the assembly in the tree view that contains the offline plug-in.
  2. Write down the value in the Public Key Token field to use in the next procedure.

Create a sub-key under the AllowList registry key

  1. On the host computer that runs Microsoft Dynamics CRM for Outlook, select Start, and then click Run.
  2. Type regedit in the text field and click OK to start the registry editor.
  3. Expand the tree view folders and navigate to the following registry key:

    My Computer\HKEY_CURRENT_USER\Software\Microsoft\MSCRMClient\AllowList

  4. Right-click the AllowList key, select New, then click Key.
  5. Type the offline plug-in assembly's public key token value as the name of the new key.

The following figure shows the AllowList with two sample keys. The keys were named with the public key token value of two assemblies containing offline plug-ins.

Adding a sub-key to the AllowList key

 

Test the Plug-in in Offline Mode

Test the plug-in by creating an account. This will trigger the plug-in code to run.

  1. Open Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access and verify that the client is online. There should be a Go Offline button in the Microsoft Dynamics CRM toolbar.
  2. Click the Go Offline button. After a short while of processing, Microsoft Dynamics CRM for Outlook with Offline Access is placed in offline mode.
  3. Close the Synchronizing Microsoft Dynamics CRM Data dialog box when the processing is finished.
  4. In the toolbar, click New Record and then click Account.
  5. Enter a unique Account Name and click Save and Close.
  6. After Microsoft Dynamics CRM finishes saving, click on the Activities link under Details.
  7. You should see a new activity created for the new account with the subject Send e-mail to the new customer.

In this walkthrough the plug-in was registered for both online and offline execution. When Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access goes from offline to online mode, synchronization of the client is performed with the Microsoft Dynamics CRM server. During this synchronization period the account that was created in Outlook while offline is now created on the server. Because the plug-in is registered for account creation in online mode, the plug-in executes a second time and creates a second follow-up activity. If this is undesirable behavior, you can either design your plug-in code to work around this issue or register the plug-in for offline mode only.

Test the Plug-in in Online Mode

The procedure to test the plug-in in online mode is similar to testing in offline mode.

  1. Open Microsoft Dynamics CRM for Outlook with Offline Access and verify that it is online. There should be a Go Offline button in the Microsoft Dynamics CRM toolbar.
  2. In the toolbar, click New Record and then click Account.
  3. Enter a unique Account Name and click Save and Close.
  4. After Microsoft Dynamics CRM finishes saving, click on the Activities link under Details.
  5. You should see a new activity created for the new account with the subject Send e-mail to the new customer.

See Also

Reference


© 2010 Microsoft Corporation. All rights reserved.


Show:
© 2014 Microsoft