Arun's blog

Unit testing a CRM Plug-in

2012-02-19T05:24:00Z

As a TDD aficionado I never feel my code complete without writing unit tests. However you may not always be lucky to be working with a framework which has been designed with testability in mind, for e.g. ASP.NET MVC or WF4. CRM 2011’s plug-in programming model is definitely not one that belong to the “testable” category. This weekend I decided to venture out to see what it takes to unit test a a CRM plug-in.

CRM plug-ins are designed to be run inside the CRM server’s execution environment (mostly sandboxed) and often access CRM’s web services to create or retrieve entities. Hence it was clear that we have to use test doubles to make the plug-in run without the CRM environment. I decided to go with Moles framework from MSR (Microsoft Research), which can be downloaded for free. If you are not familiar with test doubles, I strongly recommend you read Martin Fowler’s concise and precise piece on it here or take a look at the xunitpatterns.org website.

Download and Install Moles Framework

Download and install Moles framework from here. Remember to download x86 or x64 versions depending on your VS 2010 version.

CRM Plug-in

The sample CRM plug-in shown in this blog leverages CRM 2011 developer toolkit. Though I strongly recommend it, it is in no way a pre-requisite for understanding how to unit-test a plug-in. Code below shows a very simple plug-in which validates the “telephone1” attribute of the account entity and throws an exception if the phone number is not a valid US phone number.

 protected void ExecutePreValidateAccountCreate(LocalPluginContext localContext)
{
    if (localContext == null)
    {
        throw new ArgumentNullException("localContext");
    }
    var account = localContext.PluginExecutionContext.InputParameters.ContainsKey("Target") ? 
        localContext.PluginExecutionContext.InputParameters["Target"] as Entity : null;
    if (account == null) return;
    if (!account.Attributes.ContainsKey("telephone1")) return;
    string phonenumber = account.Attributes["telephone1"] as string;
    if (string.IsNullOrEmpty(phonenumber)) return;
    ValidatePhoneNumber(phonenumber);
}
 
private void ValidatePhoneNumber(string phoneNumber)
{
    Regex regexObj =    new Regex(@"^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$");
 
    if (!regexObj.IsMatch(phoneNumber))
    {
        throw new InvalidPluginExecutionException("Invalid phone number" + phoneNumber);
    }
}
 

Unit test project

Add a test project to your CRM 2011 solution. Add a reference to Microsoft.Moles.Framework assembly

Add references to Microsoft.Xrm.Sdk and your plug-in assemblies to the test project.

Creating Unit test

Let us start writing the unit test for the plug-in. The code in your unit test can be as simple as creating an object of your plug-in class and calling its Execute method.

Unit test
 [TestClass]
public class PreValidateAccountCreateTest
{
    [TestMethod]
    public void TestPreValidateAccountCreate()
    {
    }
}
 

However Execute method of the IPlugin Interface expects a parameter of type IServiceProvider from the System namespace in mscorlib assembly, a standard interface existed since .NET framework 1.0 days. IServiceProvider is nothing but a container (or dictionary) of services, indexed by the types of the contained services (or its abstract base classes/interfaces). When the plug-in is being executed by the CRM platform, CRM platform is responsible for creating the IServiceProvider object populated with services needed by the plug-in and passing it to the Execute method. In a unit test method it is the responsibility of the author to provide all the dependencies required to run (test) the code being tested. Though you can manually create your own implementation of IServiceProvider and pass it to the Execute method, Moles framework comes handy here.

Creating Stubs

Right-click the “References” node of your Test project to “Add moles assembly for mscorlib”. This action add a new file to your project “mscorlib.moles”. Compile your test project and you will see that a reference to mscorlib.Moles assembly has been added to your project automatically.

mscorlib.moles assembly contains stubs for various interfaces -including IServiceProvider- from the mscorlib assembly. What this means is you can re-write your boilerplate unit test code as shown below

Unit test
 [TestClass]
public class PreValidateAccountCreateTest
{
    [TestMethod]
    public void TestPreValidateAccountCreate()
    {
        var serviceprovider = new SIServiceProvider();
        var plugin = new PreValidateAccountCreate();
        plugin.Execute(serviceprovider);
    }
}
 

Take a look at the SIServiceProvider class, which is present in the System.Moles namespace. The name of the class merits some decoding since it will help you understand the standard nomenclature moles framework uses. The class is named SIServiceProvider because it is a “Stub” for “IServiceProvider” interface. Any stub class moles framework creates will be named as per this rule. This stub class, more than implementing the IServiceProvider interface, allows you to substitute methods and properties you are interested in (or your code -being tested-uses).

We have used the stub class for IServiceProvider in the above code, however it is not complete without stubbing the GetService method of IServiceProvider. Below is the temporary stub for the GetService method

 serviceprovider.GetServiceType = delegate(Type type)
{
    if (type.Equals(typeof(IPluginExecutionContext)))
        return null; //stub of pluginexecution context;
    else if (type.Equals(typeof(IOrganizationServiceFactory)))
        return null;//stub of organization service factory;
    return null;
};
 

when CRM platform executes a plug-in it expects the IServiceProvider container object to contain three objects of type ITracingService, IPluginExecutionContext and IOrganizationServiceFactory. ITracingService is not mandatory if you are not doing any tracing, hence I have omitted the check in the GetService method stub.

As you guessed correctly, I am going to add stubs for IPluginExecutionContext and IOrganizationServiceFactory and they will be named as SIPluginExectuionContext and SIOrganizationServiceFactory. Since these interfaces are present in the Microsoft.Xrm.Sdk assembly, let us add a mole file and create the stub classes. Right-click the Microsoft.Xrm.Sdk reference node and “Add Moles Assembly”.

This will add a new file called Microsoft.Xrm.Sdk.moles to the project. Build your test project, note that a new reference to “Microsoft.Xrm.Sdk.Moles” assembly is added automatically. This assembly contains stubs for interfaces explained earlier. The refactored unit test method using these stub classes should look like

 [TestMethod]
public void TestPreValidateAccountCreate()
{
    var serviceprovider = new SIServiceProvider();
    var pluginec = new SIPluginExecutionContext();
    var orgsf = new SIOrganizationServiceFactory();
 
    serviceprovider.GetServiceType = delegate(Type type)
    {
        if (type.Equals(typeof(IPluginExecutionContext)))
            return pluginec;
        else if (type.Equals(typeof(IOrganizationServiceFactory)))
            return orgsf;
        return null;
    };
 
    var plugin = new PreValidateAccountCreate();
    plugin.Execute(serviceprovider);
}
 

We have successfully stubbed the GetService method of the IServiceProvider interface. Similarly we have to stub out methods and properties of IPluginExecutionContext and IOrganizationServiceFactory.

Following code shows how we can stub IPluginExecutionContext interface.

 var pluginec = new SIPluginExecutionContext();
pluginec.UserIdGet = delegate() { return new Guid(); };
pluginec.StageGet = delegate() { return 10; };
pluginec.MessageNameGet = delegate() { return "Create"; };
pluginec.PrimaryEntityNameGet = delegate() { return "account"; };
 
var parametercollection = new ParameterCollection();
var accountentity = new Entity("account");
accountentity.Attributes.Add("telephone1", "123456"); ;
 
parametercollection.Add("Target", accountentity);
pluginec.InputParametersGet = delegate() { return parametercollection; };
 

Line number 2-4 provides your own implementations of various properties because these are used in the constructor of your plug-in as shown below

 base.RegisteredEvents.Add(new Tuple<int, string, string, Action<LocalPluginContext>>(10, "Create", "account", new Action<LocalPluginContext>(ExecutePreValidateAccountCreate)));
 

Lines 5-12 stubs properties as required by your plug-in code, especially InputParameters propery, “Target” indexer and “telephone1” attribute.

 var account = localContext.PluginExecutionContext.InputParameters.ContainsKey("Target") ? 
    localContext.PluginExecutionContext.InputParameters["Target"] as Entity : null;
if (account == null) return;
if (!account.Attributes.ContainsKey("telephone1")) return;
string phonenumber = account.Attributes["telephone1"] as string;
 

It is time to provide a stub implementation for IOrganizationServiceFactory

 var orgservice = new SIOrganizationService();
 
var orgsf = new SIOrganizationServiceFactory();
orgsf.CreateOrganizationServiceNullableOfGuid = delegate(Guid? userid) { return orgservice; };
 

CRM uses IOrganizationServiceFactory interface’s CreateOrganizationService method to return an implementation of IOrganizationService interface. IOrgnizationService interface as well as CreaeOrganizatinService method are stubbed as shown in the above code sample.

It is time to run your test method. However, if you look at the phone number “12345”, you already know that your code is going to throw a InvalidPluginExecutionException. Add the ExpectedException attribute to your test method so that it knows what exception to expect. Your test method should like

 [TestMethod]
[ExpectedException(typeof(InvalidPluginExecutionException))]
public void TestPreValidateAccountCreate()
{
    var serviceprovider = new SIServiceProvider();
 
    var pluginec = new SIPluginExecutionContext();
    pluginec.UserIdGet = delegate() { return new Guid(); };
    pluginec.StageGet = delegate() { return 10; };
    pluginec.MessageNameGet = delegate() { return "Create"; };
    pluginec.PrimaryEntityNameGet = delegate() { return "account"; };
 
    var parametercollection = new ParameterCollection();
    var accountentity = new Entity("account");
    accountentity.Attributes.Add("telephone1", "123456"); ;
 
    parametercollection.Add("Target", accountentity);
    pluginec.InputParametersGet = delegate() { return parametercollection; };
 
    var orgservice = new SIOrganizationService();
 
    var orgsf = new SIOrganizationServiceFactory();
    orgsf.CreateOrganizationServiceNullableOfGuid = delegate(Guid? userid) { return orgservice; };
 
    serviceprovider.GetServiceType = delegate(Type type)
    {
        if (type.Equals(typeof(IPluginExecutionContext)))
            return pluginec;
        else if (type.Equals(typeof(IOrganizationServiceFactory)))
            return orgsf;
        return null;
    };
 
    var plugin = new PreValidateAccountCreate();
    plugin.Execute(serviceprovider);
}
 

Right-click your test method and run it inside visual studio. Observe the Test Results window to see whether it passed. You can add another test method with a valid US phone number to test the success code path of your plug-in. Alternately you can use Microsoft Pex for parameterizing your input values and create PUTs (Parameterized Unit Tests).

Multiparadigmatic .NET series from Ted Neward

2011-03-27T07:06:00Z

1. Part 1

2. Part 2

3. Part 3

4. Part 4

5. Part 5

6. Part 6

Getting really started with Mce

2009-01-16T09:23:40Z

This post is long overdue. I was held up with activities on CCF 2009 SP1 release, which will be out shortly. Let us get started with installing Mce.

Installing Mce

Mce is a core component of CCF framework. You can choose to install Mce framework components by selecting the “MCE Components” option under Framework in CCF 2009 installer as shown below

Mce software factory and DSLs are present under Developer Tools and Samples section in the installer as shown below

Please note that you should have Guidance Automation Extension version 1.4 installed for using Mce Software Factory. You can download it from http://www.microsoft.com/downloads/details.aspx?FamilyId=DF79C099-4753-4A59-91E3-5020D9714E4E&displaylang=en

Verifying Mce Installation

Mce framework is nothing but a set of .NET assemblies and you can find these in the Framework directory under your CCF 2009 installation folder.

To verify Mce software factory installation go to Add or Remove programs Applet in control panel and make sure you have the following components installed. If you have both Visual Studio 2005 and 2008 you will see Software Factory, WorkUnit and Logical View DSLs installed separately for 2005 and 2008.

Make sure that there is new Solution type “MCE Solution” in the New Project dialog in Visual Studio under “Guidance Packages”

After you create a Mce Solution you should see three menu options to create specific Mce project types.

In the Add new Item dialog you should see Item Templates corresponding to LogicalView and WorkUnit DSLs

In the next post I will show you how to create your first multi-channel enabled application

Getting started with Mce

2008-10-28T21:07:50Z

Understanding UI Process

Before we delve into Mce let us try to dissect the term UI process. A UI process should have its controller logic, in our case it is going to be Windows Workflow. Since a controller interacts with the views as well, we need to hold a reference to the views participating in the UI-Process. Next is the data (a.k.a Model in MVC). Hang on, the UI process that we are talking here has to be reusable across channels, hence it cannot be holding references to the views it driving.

There are multiple ways of fixing this problem, the most common is using a set of fixed interface that every participating view has to implement and controller (Workflow) communicates to the view(s) through this interface. This looks fine when you are developing a fresh set of user interface elements. What if you would like to re-use some of the views (for e.g. windows user controls, web user controls etc) from your existing application? Re-writing each view to implement the interface is not going to be that easy. Another approach is to write the controller logic against a set of UI abstractions. i.e. your controller logic will be written against a set of user interface abstractions instead of an interface or the views themselves, let us call this abstraction as a Logical View.

WorkUnit

A reusable UI process contains the controller logic + a set of logical views (against which controller logic is written) . This concept is abstracted as a WorkUnit in Mce. Hereafter I will not be using the term UI process a lot , instead you will see references to WorkUnit a lot. A WorkUnit in Mce represents a reusable navigation logic written using the Workflow foundation workflow and associated Logical Views. I deliberately omitted the discussion about data here, but we will come back to how data is handled in a WorkUnit in Mce.

LogicalView

As mentioned earlier, LogicalView is a channel independent abstraction of a Physical View (Windows form, Web User control, etc.). Hence a LogicalView contains properties (name and data type), events the view can raise and commands that you can perform on the view (or else functions that you can call on the view, if you have an instance of the view).

Navigational Event

In Mce a Navigational Event represents channel independent abstraction of an event that the physical view will raise, for e.g. if the user clicks the next button in the physical view, you may want your controller to react a Navigational Event called "Next". In short you can write your controller logic against logical views and navigational events from those logical views.

Navigational Workflow

Mce Navigational Workflow is the controller logic that you write using Windows Workflow foundation. You can write state machine or sequential workflows, state machines are the ones most commonly used.

Where is the Model?

We talked about controller and views. How about model/data?. In Mce data that the controller interacts is actually represented as properties in the LogicalView itself. Hence the navigational workflow that you write is actually a controller + data/Model. This is done for the obvious reason of moving the controller logic across channels. When you move the controller logic from one channel to another you get the updated data values as well.

Enough of this diatribe, in my next post we will get our hands dirty with Mce in CCF 2009, and I will be covering more concepts and related terminologies as we proceed

Introducing CCF2009 and Mce

2008-10-22T10:10:00Z

UI Process

Not a lot has been talked about UI Processes. You do a live search or google search for UI process and first result you get is Microsoft UI process application block. I tried Wikipedia for a standard definition without any luck. The only definition I could find is again from Microsoft UI Process application block tutorial which is

A user interface process — A set of user-related activities that achieve a goal.

Microsoft UI Process Application block is the popular framework in .NET which allows you to implement UI Process functionalities in your application. But if you look at the server side counterpart (I mean, Business process orchestration) we have many standards products and frameworks ranging from BizTalk to many ESB frameworks. Lets see why it pays to care about UI Process as well

MVC and UI Process

As the definition implies UI Process defines a navigational logic that you perform to achieve a goal (e.g. pay your Credit card bills online, Set archiving rules in outlook etc.). To abstract away this navigational logic, we can use good old MVC pattern. Hence often when you talk about UI Processes you invariably end up talking about MVC and how you can centralize the controller logic

Controller and Windows Workflow Foundation

Windows workflow foundation’s support for creating state machines makes it an excellent framework for creating our controller logic. You can think of the navigational logic in a UI process as a set of state transitions that the views undergo in response to user events. Workflow Foundation’s excellent designer support makes it more compelling to use it to define your controller logic

Reusing the controller logic

Why should we ever reuse our controller logic? Enterprises are developing applications that already support multiple channels of interaction and most of them have ambitious plans for supporting more channels in future. A channel here means the medium that user interacts with your application. E.g. Web, Windows, Mobile are all possible channels. There are two compelling reasons for creating reusable controller logic.

1. To support more channels in future without re-writing your controller logic.

2. Modify the controller logic centrally and at once and reflect it on multiple channels simultaneously

Most of the complex processes an enterprise has, do not necessarily start and end in one channel, instead they span across multiple channels. In this case how do you carry forward your navigational logic from one channel to other? Again Windows Workflow Foundation provides excellent support with passivation and rehydration of the state of the workflow. This means that if you write your controller logic (Navigation logic) using Windows Workflow Foundation you may be able to passivate the workflow in one channel and rehydrate in another channel. But again the workflow has to be channel agnostic.

Once you find that the reusability aspect of your controller logic is important, you start thinking how do I write my controller logic (State Machine Navigational Workflow) in a channel agnostic way? For e.g. you write a state machine workflow that drives a set of windows forms and you want the same workflow to drive a set of web forms or WPF forms. The best way to do is to create your workflow against a set of UI abstractions and depending on the channel the workflow is running it can drive either a set of windows forms or web forms or WPF forms.

CCF2009 and Mce framework

CCF2009 ships with Multi Channel Engine (Mce) framework which helps you to create channel agnostic workflows for your controller logic. Mce defines a set of UI abstractions and helps you to define your navigational workflow (controller logic) in a channel agnostic manner. In this blog I will be talking about how you can leverage CCF and Mce to create channel independent reusable UI Process for your application