With the release of RC2 of Microsoft System Center Configuration Manager 2012 Package Conversion Manager (PCM) we get to experiment with a new feature; PCM Extensibility. PCM Extensibility is an extensibility point for PCM that provides IT shops with an opportunity to customize the package conversion process with the goal of speeding up the retirement of wrappers commonly used with Classic Software Dist. programs.

• The Why: Many Configuration Manager customers have Classic Software Dist. packages with custom logic and wrappers that are unique to their environment. The Application Model in SCCM 2012 addresses many of the reasons customers originally invested in customizations. PCM allows our customers to unwind the extensibility of their program wrappers and to take full advantage of the App Model. Essentially PCM helps them divest in custom wrappers for scenarios that are a 1st class citizen within the new App Model.
• The How: Unlock the the full breadth and  scope of the App Model SDK during the conversion process by providing a custom executable with access to a copy the XML digest from a converted Application by building a PCM Plugin.
• The What: An extensibility option called the PCM Extensibility.

The Basics

On the high level a PCM plugin is an executable that is launched by the conversion and the analysis process. Below is a diagram that shows the basic interactions. The dashed line represents the process boundary between PCM and the plugin processes. The Application object that is created by PCM is serialized to XML using the SccmSerializer class found within the App Model SDK. In the diagram below the plugin is reading and manipulating the XML. Once the plugin has made all necessary changes it overwrites the original file with the updated XML. Once the plugin process exits PCM deserializes the Application object from the updated XML and continues with the conversion or analysis process. PCM passes three arguments via the command line when launching the Plugin. It passes Package ID, full path to the XML digest of the serialized Application, and the name of the site server that the console is connected to.

It’s important to note that the PCM Plugin is ran on a per package basis. Or put differently, is executed within the context of a single package-to-app conversion. So  if 5 Automatic packages have been selected for Conversion the plugin will be launched 5 times.

Configuration

There are several options related to the PCM Plugin. These options are controlled via the Microsoft.ConfigurationManagement.exe.config file for the Admin Console. The Microsoft.ConfigurationManagement.exe.config file found within the “bin” folder under the Admin Console install location. The sample download at the bottom of this post contains a sample .config file.

Config Sections

The first step in setting up a PCM Plugin is to add a PCM binary to the configSections node. Add the following child node to configSections.

<section name="Microsoft.ConfigurationManagement.UserCentric.Workflow.Properties.Settings" 
               type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 
               requirePermission="false" />

Plugin Command Line

PCM launces a command shell process using a command line value specified by the .config file. At run time PCM appends to this command line three arguments. The PackageID of the source package, the full path to the XML digest of the derived Application object, and the site server that the console is connected to are appended in that order. To configure a plugin add the following setting to the Microsoft.ConfigurationManagement.UserCentric.Workflow.Properties.Settings node under applicationSettings similar to the example below.

<setting name="PcmPlugIn" serializeAs="String">
   <value>powershell.exe "C:\sample\PlugInAppModel.ps1"</value>
</setting>

Based on the PcmPlugin value specified above the complete command line that will be used to launch the Plugin will look like:
cmd /c powershell.exe “c:\sample\PlugInAppModel.ps1” ABC00002 %temp%\filename.xml MySiteServer

It’s important to note that this is the only required configuration piece to get your plugin up and running within PCM.

Plugin Timeout

PCM has a configurable Plugin Timeout threshold. If the Plugin process runs for longer than the specified duration PCM will consider that an error and skip onto the next package. Below is an example of how to configure the timeout value in milliseconds.

<setting name="PcmPlugInTimeoutMilliseconds" serializeAs="String">
       <value>100000</value>
</setting>

Plugin Exit Code

The Microsoft.ConfigurationManagement.exe.config also allows us to specify what success is in terms of process exit code. The default is 0 but if your plugin uses a different value to indicate success you can modify the setting as shown below.

<setting name="PcmPluginExitCode" serializeAs="String">
   <value>8</value>
</setting>

PowerShell Sample

To help get the community off and running with building plugins for PCM we created a sample plugin built using PowerShell. In this blog post I will cover the core concepts demonstrated by the sample, however the sample plugin goes further by showing how to achieve more advanced tasks with the App Model SDK.

Arguments

First we need to get our arguments from the command line so we know where our XML digest is.

 1: $packageId      = $args[0]

 2: $fullFileName   = $args[1]

 3: $sccmServerName = $args[2]

Loading SDK Assemblies

A plug in can work directly with the XML and use XPath to navigate the digest. This requires an intimate understanding of the schema used by the App Model but it is still a valid approach. In the sample plugin we show how to use the App Model SDK via PowerShell so we don’t have to fiddle about with XPath.

 1: #Loads Application Model into Application Domain

 2: LoadSccmAssemblies

To load the SDK Assemblies for working with the Application class we use the following function from SharedFunctions.ps1

 1: #Load Sccm Assemblies

 2: function LoadSccmAssemblies()

 3: {

 4:     $sccmPath = "C:\Program Files (x86)\Microsoft Configuration Manager\AdminConsole\bin\"

 5:     $filesToLoad = "Microsoft.ConfigurationManagement.ApplicationManagement.dll","AdminUI.WqlQueryEngine.dll", "AdminUI.DcmObjectWrapper.dll" 

 6:     

 7:     Set-Location $sccmPath

 8:     [System.IO.Directory]::SetCurrentDirectory($sccmPath)

 9:     

 10:     foreach($fileName in $filesToLoad)

 11:     {

 12:        $fullAssemblyName = [System.IO.Path]::Combine($sccmPath, $fileName)

 13:        if([System.IO.File]::Exists($fullAssemblyName ))

 14:        {   

 15:            $FileLoaded = [Reflection.Assembly]::LoadFrom($fullAssemblyName )

 16:        }

 17:        else

 18:        {

 19:             Write-Host ([System.String]::Format("File not found {0}",$fileName )) -backgroundcolor "red"

 20:        }

 21:     }

 22: }

Deserialize

Next we need to deserialize the XML digest into an instance of Application.

 1: #Deserialize XML file

 2: $applicaton = GetApplicationObject $fullFileName

This is also handled by a function from SharedFunctions.ps1.

 1: #Deserialize XML into Application

 2: function GetApplicationObject([string]$xmlFilePath)

 3: {

 4:    $fileContent = get-content $xmlFilePath -readcount 0   

 5:   [Microsoft.ConfigurationManagement.ApplicationManagement.Serialization.SccmSerializer]::DeserializeFromString($fileContent,$false)

 6: }

Modify

Now that we have an instance of Application to work with we can start to modify it. One easy example is changing the Title of the Application

 1: #Modifies Application Name

 2: $applicaton.Title = $applicaton.Title + "_ModifiedByPlugIn"

 3: $applicaton.DisplayInfo.Current.Title = $applicaton.DisplayInfo.Current.Title + "_ModifiedByPlugIn"

Unwinding Your Wrapper

Now that we have modified the title of our Application we need to move on to some more serious work. For example if your programs are currently wrapped with a custom executable or script a key piece to using the PCM Plugin to move away from a wrapper is updating the command line within the Deployment Type to point directly at an MSI. Below we show how one can get to the first DT in the Application and update the InstallCommandLine property to point at the MSI directly. If wrappers are being used to facilitate uninstall scenarios then using the plugin to populate the UninstallCommandLine property will also be valuable.

 1: $deploymentType = $applicaton.DeploymentTypes[0]

 2:         

 3: $deploymentType.Installer.InstallCommandLine = 'MSIExec.exe /i "SimpleMSI.msi" /q'

 4: $deploymentType.Installer.UninstallCommandLine = 'MSIExec.exe /uninstall "SimpleMSI.msi"'

Analysis and the Plugin

One important point that should be called out is that the Plugin is also invoked during Analysis and the Readiness rule set is applied to the derived Application after the plugin completes. The implication is that the PCM Plugin has an opportunity to modify the Application before readiness rules are applied. This gives the plugin the ability to affect the Readiness state of the package. The example below shows how a plugin can have an impact on Readiness.

Getting More Packages into the Ready State

The PCM Plugin concept is intended to help with moving away from wrappers that are made obsolete by the new Application Model. With that said you can create a plugin for a number of reasons. For example one might create a Plugin to get more packages into the Ready state. The number one blocker to getting your packages into the Ready state will be missing detection methods. PCM is limited in its ability to natively find detection methods. PCM can only find a detection method if an MSI can be located in the program command line. With the plugin we have an opportunity to add the capability to create an enhanced detection method or supply a product code. To determine if a Deployment Type is missing a detection method the plugin will need to examine the ProductCode and EnhancedDetectionMethod properties of the Installer within the DeploymentType instance. If both of these are empty then a detection method will be needed. Below is an example of how to set the ProductCode property to a random GUID. This would be ill-advised in a production  environment but gives an example of how to modify the ProductCode value.

 1: foreach($i in $application.DeploymentTypes)

 2:    {

 3:        if($i.Installer.ProductCode -eq " ")

 4:        {

 5:           $i.Installer.ProductCode = [Guid]::NewGuid().ToString()

 6:        }

 7:    }

Sample Code

Here is a link to the Sample code:

Quick note: The App Model SDK is still under development and some of the class referenced below are bound to change between Beta 2 and RTM.

Start with Application

To get started you’ll need to add a reference to the following assemblies found in the CM 2012 Console install directory:

• Microsoft.ConfigurationManagement.ApplicationManagement.dll
• Microsoft.ConfigurationManagement.ApplicationManagement.MsiInstaller.dll

The first step in creating your first Application in the 2010 App Model is to create an instance of Microsoft.ConfigurationManagement.ApplicationManagement.Application.

//creat an instance of Application 
ObjectId appId = new ObjectId("Authoring_Scope_Id",
 "Application_"+Guid.NewGuid().ToString());
Application app = new Application(appId);
app.Title = "New App";
app.Version = 1; 

The constructor for Application takes an instance of ObjectId which indicates the Authoring Scope and Logical Name of the Application. These are in the form of “ScopeId_5D0545B8-46E1-4F48-B165-B8870DAE1C1C" and “Application_b3628303-eeb6-41af-a15c-175c12f3bd6a” respectively. The Authoring scope is unique per Primary Site Server and you can get that from WMI. Supplying a fake Authoring Scope ID should work just fine for testing purposes. If you plan on deploying this to a client you should do the work to get the actual Site Scope Id. It should also be noted that the “Version” property does not refer to the version of the Application that your are creating. It indicates the revision of the app in terms of Application revisions which is a new feature in 2012.

Add Localized Display Info

The various Application properties such as Title are what we see in the Admin Console. The end user via Software Center or the Software Catalog see different information. The end user sees information contained in an instance of DisplayInfo that can be localized to the language of the end user. This is done by adding an instance of DisplayInfo along with localized metadata for each language you want to support.

//cerate DisplayInfo //this is the localizable info that the end user will see in Software Center 
AppDisplayInfo displayInfo = new AppDisplayInfo(); 
displayInfo.Title = "My App"; 
displayInfo.Language = CultureInfo.CurrentCulture.Name; 
displayInfo.Description = "My first App"; 
app.DisplayInfo.Add(displayInfo);

Here I am using the same language as the current executing process “en-US”, but you could use any language identifier.

Add a Deployment Type

For those not familiar with the App Model the Application is the abstract definition of an application and the Deployment Type represents the concrete instance of the app. To make our app work we need to associate an installer and content with the Application instance. This is done with a DeploymentType.

//Add DT ObjectId dtId = new ObjectId("Authoring_Scope_Id",     
 "DeploymentType" + Guid.NewGuid().ToString()); 
DeploymentType dt = new DeploymentType(dtId, MsiInstaller.TechnologyId); 
app.DeploymentTypes.Add(dt); 
dt.Title = "My First DT";
dt.Version = 1; 

Again we see the use of ObjectId but we are using the “DeploymentType_” prefix for Name. Once we have the DeploymentType created we add it to Application.DeploymentTypes. The TechnologyId paramter in the DT constructor indicates what type of DT we are creating. We are creating an MSI type DT so we use the static property found on Microsoft.ConfigurationManagement.ApplicationManagement.MsiInstaller that equates to the string “MSI”.

Setup the MsiInstaller

Our new DT has been added to our Application. DeploymentType has a property called “Installer” that exposes the instance of Installer that we need to work with. The DT constructor was nice enough to supply us with an instance of MsiInstaller so we just need to configure it.

//configure MSI installer to have a product code detection method 
MsiInstaller installer = dt.Installer as MsiInstaller; 
Guid fakeProductCode = Guid.NewGuid(); 
installer.ProductCode = "{" + fakeProductCode.ToString() + "}";

//set commandline 
installer.InstallCommandLine = "MSIExec /i MyApp.Msi";

One critical component to any DT is its Detection Method. The Detection Method indicates how the CM Client is suppose to know if the app is installed or not. This is critical as the App Model is state based. If you get the Detection Method wrong the client will think the app is not installed and will attempt to install it every time Global Evaluation runs (every 7 day I believe) even if the app is installed. The nice part about working with MSIs is that we can just specify a Product Code and the rest is handled for us. The Product Code format is a Guid wrapped with { } such as {27aae8e3-e733-4256-a37f-dc1e0287da9f}.

Add Content

Next we need to associate our DT and MsiInstaller with actual content so the client has something to install.

//Add content to the DT 
Content installerContent = new Content(); 
installer.Contents.Add(installerContent); 
installerContent.Location = @\\SomeServer\content\MyAppDir; 
//add MSI file to content 
ContentFile msiFile = new ContentFile(); 
msiFile.Name = "MyApp.Msi"; 
installerContent.Files.Add(msiFile);

When setting the Name property on ContentFile use a path that is relative to the path specified by “Location”.

Serializing the Application

We are almost ready to send our app to the site to deploy to clients. Before we do that we need to serialize our instance of Application. We use a special serializer found in Microsoft.ConfigurationManagement.ApplicationManagement.Serialization called SccmSerializer. This serializer will do some addition verification for us to check for invalid properties.

//serialize app. string appXml = SccmSerializer.SerializeToString(app, true);  

Committing the App to the Site

The last step to creating our app is to use the CM WMI provider to save our serialized data to the site server. To do this we need to create an instance of SMS_Application. I’m not going to go into great detail on working with WMI here as there are a ton of articles that cover that subject. But here is a basic method for getting an instance of SMS_Application from the provider.

//serialize app. 
string appXml = SccmSerializer.SerializeToString(app, true); 
ManagementObject appInstance = null; 
ManagementPath path = null; 
ObjectGetOptions options = null; 
ManagementClass appClass = null; 
try 
{
 ManagementScope scope = 
 new ManagementScope(@”\\SiteServer\root\Sms\Site_SiteCodeGoesHere”);     
 path = new ManagementPath("SMS_Application");     
 options = new ObjectGetOptions();     
 appClass = new ManagementClass(scope, path, options);
 appInstance = appClass.CreateInstance(); 
} 
finally 
{
 appClass.Dispose(); 
}

The only property we need to set here is SDMPackageXML. We set SDMPackageXML to the serialzed XML string stored in appXml and call Put() to save our app to the site.

appInstance.Properties["SDMPackageXML"].Value = appXml; appInstance.Put();

You should now have an app that is ready to deploy!

There are a lot of other properties associated with the App Model that we did not explore that can impact how an App behaves on the client. This post covers jus the most basic. In upcoming posts I’ll cover more advanced topics such as DT dependencies and Enhanced Detection Methods.

• The Why: Apart from being expensive in terms of time and effort, every time a bug is handed off between Dev and Test is an opportunity to drop the ball or for confusion to creep in.
• The How: Capture bug repro steps as an automated test that any developer can run without assistance from test.
• The What: Reduce bug hand-offs and interdisciplinary interactions to move a bug to the “Closed” state.

The cost of finding a defect in test and resolving the issue via a bug is an expensive process in terms 'of time and effort. The ideal solution is to find bugs prior to check-in with TDD or gated check-ins. But we live in a world where that doesn’t always work and the bug is still a part of life.

Within the Package Conversion Manager 2012 project I am currently engaged in we have put a lot of effort into test automation through TDD and other forms of testing. We’ve essentially implemented the Agile development model that my colleague John Socha-Leialoha has described here. As the project matured we settled on a bug process that I have found to be a bit more efficient than what I have experienced on other more traditional or waterfall projects. It’s this process that I wanted to highlight in this blog post.

Traditional Bug Process

If you’ve worked on a traditional waterfall style software project you are probably familiar with a certain bug process. A tester finds an issue then files a bug. Invariably there is some back and forth on the repro steps with the dev. Once the bug is taken and fixed the developer resolves the bug and assigns it back to the originating tester to verify the fix. The tester executes a test or set of tests to ensure that the issues was addressed. If actually fixed it’s resolved as closed. Below is a diagram that shows a typical bug process minus the triage step.  In blue we see the steps taken by a tester and red indicates the steps taken by a developer. In the diagram below we see two transitions or hand-offs. It is these hand-offs that I want to avoid as these are very expensive and each hand off is an opportunity to drop the ball or for confusion to creep in. Keep in mind that the process shown below is a best case scenario for a waterfall style project.

In some cases there can be additional hand-offs. During my testing years I was all to familiar with the “no repro” trick. As a result there was a substantial amount of back and forth with a bug as I attempted to convey the complexities and nuances of the actual issue via a text field in the bug form. In the below diagram we see a less than ideal situation where the number have hand-offs have been doubled.

Simplified Bug Process

Within the PCM project our testers will capture each bug in an automated test that I as a developer can easily run to validate my fix. If the automated test that discovered the bug is a high level acceptance test with a great deal of leverage I will replicate the failure in a unit test that is targeted at that specific area. These tests are created using the Unit Test framework (we use it for all forms of tests) found in Visual Studio / TFS. By having all automated tests be part of the main product solution it is easy for me as a developer to run all tests or a specific test. This process hinges on the ability of the developer to easily run any automation created by a tester. The main benefit here is that once the tester has filed the bug and linked it with an automated test the tester is essentially done with this bug. The automated test serves as clearly defined and very specific repro steps. Gone are the days of a bug being resolved as “No Repro”. The diagram below shows the simplified process that we are using.

As you can see we have effectively reduced the number of hand-offs to one greatly reducing the overhead and risk associated with traditional processes shown above. This has had the effect of creating a lighter weight and crisper bug process that keeps the tester focused on expanding test coverage and product quality and not on my dirty laundry.

Team Dynamics & Culture

It is technically feasible that any team could use this process, however it is likely that any team that is in a position to be successful with this approach has a certain culture with regard to test. Such a team will probably maintain a culture where the test team is in a position to place the responsibility of running test automation to verify the fix with the development team. Not every team works to put test in the driver seat on such issues which can server as a blocker to implementing the streamlined process described above.

I’ve been working with Workflow Foundation for a few year now and I’ve become a huge fan of the technology. Working in the enterprise software space I find it to be a natural fit as a solution for a great deal of scenarios. But (there is always a but) if you have ever been charged with the task of unit testing workflow activities or practice TDD you are probably familiar with how frustrating it can be. For what ever reason the Workflow team wasn’t overly concerned with unit test-ability and in my  opinion were overly aggressive in marking constructors as internal and the like. Unit testing is primarily concerned with testing the smallest unit of functionality possible which is typically a single method. With Workflow Activities this is very difficult. For example you may want to unit test the Method “Execute” on your CodeActivity which takes an instance of CodeActivityContext, but the constructor is marked internal and it doesn’t implement an interface that we can leverage to create Stand-In classes. The usage of interfaces to create and pass in Stand-In classes is my preferred method of isolating the system under test to small testable chunks so I find this especially troublesome. But since that options isn’t available to us when we are working with Activities we must do something else.  One option I’ve found useful is an approach the uses Moles from Microsoft Research that is based on CLR Detours.

Moles

Moles is part of the Pex & Moles project from MSR that leverages a concept called Detours. a Detour is when the memory location for a specific method on a specific instance is updated to point to a mock class with the same method signature. In other words this gives us a back door to wiring in mock functionality. Below is a brief example of how Moles works but a full explanation  of Moles is out of scope for this post so if you are new to Moles head on over to MSR and check out their demos and How-Tos.

Moles and Workflow Activities

Below is a diagram showing the basic architecture of how I’ve chosen to unit test activities. Starting from the unit test, Moles and a Test Stand-In classes are used to manipulate and confine the system under test (the Workflow Activity). Moles is used to wire in delegates that allows us to eliminate pieces of typical Activity execution that are not necessary parts of our test such as getting values from a InArgument which normally incorporates complex WF infrastructure. The test Stand-In is a simple component that replaces production classes with simplified test versions that provide test hooks and very predictable behavior. You’ll also see the use of test shims that expose protected members or my activities. I’ve chosen to use a derived class which uses the new keyword to create a public version of Execute which in turn calls the base version of Execute. You can use shadowing Accessors provided by the unit test wizards but I prefer the more explicit form of a derived class for the sake of a demo. Below is a diagram that shows the architecture of these unit tests and how a combinations of Test Stan-In classes and Moles allows us to focus the tests to a minimal amount of code.

Let’s dig into a Workflow specific use of Moles. Below are a few code samples of unit tests using Moles. You can find a link at the bottom of this post to the complete Visual Studio 2010 solution if you want more details about implementation.

Testing Execute on SimpleActivity

In this example we are testing SimpleActivity.Execute(CodeActivityContext context).  As part of Execute a CustomTrackingRecord is tracked and the same integer that is passed in to the InArgument<int> SomeInteger is returned. Both of these operations require the CodeActivityContext which we will need Moles to instantiate as Moles has the ability to create instances of classes even when their constructors are marked internal. Below is the code snippet for the entire unit test. After which each section is discussed in detail.

        /// <summary>
        ///A test for Execute
        ///</summary>
        [TestMethod()]
        [DeploymentItem("SampleActivities.dll")]
        [HostType("Moles")]
        public void ShouldReturnInt_WhenExecute_GivenInteger()
        {
            // Arrange
            int expected = 10;

            /// we need to create a moled CodeActivityContext so we can 
            /// get an instance from the Instance property of the moled 
            /// context as all constructors are marked as internal.
            MCodeActivityContext moledContext = new MCodeActivityContext();
            moledContext.TrackCustomTrackingRecord = (record) =>
            {
                // do nothing
            };
            /// We need to create a moled InArgument<int> so we can setup
            /// a delegate to return our expected value without using 
            /// relying on any of the complexities of the WF runtime.
            MInArgument01<int> moledInArg = new MInArgument01<int>();
            moledInArg.GetActivityContext = (ContextBoundObject =>
                {
                    return expected;
                });

            TestableSimpleActivity target = new TestableSimpleActivity();
            target.SomeInteger = moledInArg.Instance;

            // Act
            int actual = target.Execute(moledContext.Instance);

            //Assert
            Assert.AreEqual<int>(expected, actual);

        }

 

In the // Arrange section of the unit test two moles are created to handle various operations that we can’t create test Stand-Ins for. First we create a mole for the CodeActivityContext using MCodeActivityContext . Then we wire in the delegate for MCodeActivityContext .Track to MCodeActivityContext .TrackCustomTrackingRecord . This is the delegate that will serve as the Detour for the Track method. In other words this is the code that will be executed when Track is called on CodeActivityContext. In this detour delegate we don’t do any asserts but we could verify that the track call is tracking the correct data.

Next we wire in a delegate for InArgument<int>.Get. We can instantiate an InArgument but the Get call requires additional WF infrastructure that can’t reasonably reproduced outside of the WF Runtime so we detour it to get the simple behavior we want which is to just return the value expected.

Once our detours are setup we create an instance of the system under test using the Test Shim TestableSimpleActivity  which, as discussed before,  is simply a class that exposes protected members. Once we have our target object I set the SomeInteger property using the Instance property on our Mole object. We have to use the instance of InArgument<int> provided by the moled object as this is the instance that will be associated with our detours. If I just created and used another instance of InArgument<int> our detours would be ignored.

After we have the target object setup Execute is called using the instance of CodeActivityContext that is associated with our detours provided by the mole mole object moledContext.

Testing Asynchronous Execute on ComplexActivity

In the previous example I showed how to unit test the Execute method of a basic CodeActivity.  However the situation is rarely that simple in the real world. To showcase unit testing more complex activities I’ve created an activity that uses asynchronous Workflow concepts. There are several ways to create asynchronous activities. I’ve chosen to start with NativeActivity as this allows me to cover the use of bookmarks. In this unit test we are testing Execute again but this time it is an asynchronous operation and it creates a new thread using System.Task so there are a few extra steps. For example an external service is responsible for doing the actual work.

        [TestMethod]
        [HostType("Moles")]
        public void ShouldDoWork_WhenExecute_Moled()
        {
            //Arrange
            //Create test fixture version of target type to expose protected members.
            TestableComplexActivity target = new TestableComplexActivity();
            //Create a stand-in version of IWorkerService with my test hooks.
            TestWorkerService testSvc = new TestWorkerService();
            BookmarkOptions actualBmOptions = BookmarkOptions.None; 
            //Create a moled NativeActivityContext to get access to an instance.
            //And to set a Detour for CreateBookmark
            MNativeActivityContext moledContext = new MNativeActivityContext();
            moledContext.CreateBookmarkStringBookmarkCallbackBookmarkOptions
              = (bmName, bmCallback, bmOptions) =>
            {
                actualBmOptions = bmOptions;
                return new Bookmark(bmName);
            };

            //Create a moled ActivityContext to setup a detour for 
            //GetExtention<T>(Type)
            MActivityContext moledActContext = 
            new MActivityContext(moledContext.Instance);
            moledActContext.GetExtension<IWorkerService>(
              new MolesDelegates.Func<IWorkerService>(() => testSvc)
              );

            bool actual = false;



            //Act
            target.Execute(moledContext);
            //blocks until worker thread completes.
            actual = testSvc.WaitForWorkToComplete();

            //Assert
            Assert.AreEqual<bool>(true, actual);
            Assert.AreEqual<BookmarkOptions>(BookmarkOptions.MultipleResume,
            actualBmOptions);
        }

To help constrain the test to just the Execute method I’ve created a test Stand-In version of the IWorkerService extension service called TestWorkerService to synchronize the threads for me and give me access to the data being passed into the service by Execute. This is an example of leveraging interfaces for the sake of testability via Stand-Ins. Another aspect that is new to this scenario is working with bookmarks. Bookmarks are a key component to asynchronous activities and are used to indicate where the workflow is suppose to resume execution upon completion of some external process. To accommodate this in our unit test we have to setup a Moles delegate on the Moles version of NativeActivityContext.CreateBookmark method. I use the Moles delegate to  capture the BookmarkOptions value so I can validate that against an expected value using an Assert later in the unit test. Another addition to this scenario is providing a MolesDelegates.Func to handle access to the test extension service when the Execute method calls GetExtension<IWorkerService>().  Finally the last piece that is new to this scenario is the synchronization.

In the //Act section of the unit test you will notice a call to WaitForWorkToComplete on the instance of TestWorkerService. This call blocks until a WaitHandle is signaled by the new thread spawned by Execute and returns the value passed into the worker services' DoWork method. Since the behavior of the “production” worker service is simply to return the value passed in to the DoWork method the test Stand-In emulates the same behavior.

Sample Solution

The sample solution contains a few more unit test scenarios not covered here.  Below is a list of additional scenarios contained in the sample project.

• A test for the Abort method
• A test for removing MultipleResume bookmarks within bookmark callback methods
• A test for not removing MultipleResume bookmarks  when asynchronous process fails.
• A test that verifies tracking data.

While pinning down the vision and high level user stories it became apparent that the crux of this project was getting the business logic right, and doing that would require soliciting input from various subject matter experts from more than one team. Knowing this meant knowing that whatever we use to implement the business logic was going to go through much iteration as we shopped around our current thinking and incorporated feedback.

It’s all about the Flows

The nature of the FlowChart activity and its designer allows one to easily rearrange logic and components. But most importantly the Visio-esque FlowChart designer provided two key benefits. The first was that I found it was easy to stay abreast with the changes to our business logic flying out of our design and review meetings. Applying changes were simplified by the literal way in which Visio spec docs translate into a WF workflow definition. I was able to implement core behavior and be confident that it matched what was defined in the spec by simply comparing what I saw in Visio on one monitor with what I saw in the Visual Studio FlowChart designer on the other monitor.

Secondly, it made bridging the technical/nontechnical communication barrier much easier. Since I was working in an environment that was very similar to Visio and to what PMs are comfortable with, we were able to have discussions about the prototype directly. Ergo, non-technical team members were able to contribute to discussions involving the actual implementation or the “code”. This was helpful when the specifics of the implementation inevitably exceeded the detail or fidelity of the spec docs. Or put differently, it increased the relative area of the intersection between PM land and Dev land. The same could easily be achieved while working with Sequence style workflows. The key is to be deliberate about which style you are using in your design discussions and to avoid Visio’s flexible ad hoc nature to create spec diagrams that are some sort of hybrid mash up that won’t translate into some form of Workflow Foundation artifact. This increase in common ground between the disciplines has been a real asset for our team.