The underlying socket error code is SocketError.WouldBlock(10035). This is defined as WSAWOULDBLOCK in he Platform SDK header files:

#define WSABASEERR              10000
...
#define WSAEWOULDBLOCK          (WSABASEERR+35)

The managed call stack at exception time can be something like this:

System.Net.Sockets.SocketException: A non-blocking socket operation could not be completed immediately
    at System.Net.Sockets.Socket.Receive(Byte[] buffer, Int32 offset, Int32 size, SocketFlags socketFlags)
    at System.Runtime.Remoting.Channels.SocketStream.Read(Byte[] buffer, Int32 offset, Int32 size)
    at System.Runtime.Remoting.Channels.SocketHandler.ReadFromSocket(Byte[] buffer, Int32 offset, Int32 count)
    at System.Runtime.Remoting.Channels.SocketHandler.BufferMoreData()
    at System.Runtime.Remoting.Channels.SocketHandler.Read(Byte[] buffer, Int32 offset, Int32 count)
    at System.Runtime.Remoting.Channels.Tcp.TcpFixedLengthReadingStream.Read(Byte[] buffer, Int32 offset, Int32 count)
    at System.IO.BinaryReader.ReadString()
    at System.Runtime.Serialization.Formatters.Binary.IOUtil.ReadArgs(__BinaryParser input)
    at System.Runtime.Serialization.Formatters.Binary.BinaryMethodCall.Read(__BinaryParser input)
    at System.Runtime.Serialization.Formatters.Binary.__BinaryParser.ReadMethodObject(BinaryHeaderEnum binaryHeaderEnum)
    at System.Runtime.Serialization.Formatters.Binary.__BinaryParser.Run()
    at System.Runtime.Serialization.Formatters.Binary.ObjectReader.Deserialize(HeaderHandler handler, __BinaryParser serParser, Boolean fCheck, Boolean isCrossAppDomain, IMethodCallMessage methodCallMessage)
    at System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Deserialize(Stream serializationStream, HeaderHandler handler, Boolean fCheck, Boolean isCrossAppDomain, IMethodCallMessage methodCallMessage)
    at System.Runtime.Remoting.Channels.CoreChannel.DeserializeBinaryRequestMessage(String objectUri, Stream inputStream, Boolean bStrictBinding, TypeFilterLevel securityLevel)
    at System.Runtime.Remoting.Channels.BinaryServerFormatterSink.ProcessMessage(IServerChannelSinkStack sinkStack, IMessage requestMsg, ITransportHeaders requestHeaders, Stream requestStream, IMessage& responseMsg, ITransportHeaders& responseHeaders, Stream& responseStream)

WSAEWOULDBLOCK is returned by some socket APIs when the call may need to block the caller (in other words, it cannot return immediately), but the underlying socket is in non-blocking mode. For instance, the recv socket api needs to block, waiting for enough bytes to be in the input buffer, if they are not already there.

With .Net Remoting using the TCP channel, a socket should not be in non-blocking mode. However, this situation may arise on the server side of .Net Remoting if you call StartListening() on the channel when the channel is already listening.

The typical scenario is if you create the channel and call StartListening on it:

private static string StartServer()
{
     TcpChannel serverChannel = new TcpChannel(0);
     ChannelServices.RegisterChannel(serverChannel, false);
     RemotingConfiguration.RegisterWellKnownServiceType(typeof(MyHost), "MyHost",
                                                        WellKnownObjectMode.Singleton);
     serverChannel.StartListening(null);            
     return ((ChannelDataStore)serverChannel.ChannelData).ChannelUris[0];
}

The TcpChannel constructor puts the channel in listening mode, so calling StartListening at this stage creates the conditions for this behavior. Without going into too much detail on the underlying cause, suffice it to say that in this case a listening socket will experience an error while accepting the incoming connection, so it will be put into non-blocking mode. This will cause the next accept to succeed but the new connection at this point will be in non-blocking mode also.

Fortunately, if you run into this condition, the fix is easy: just remove the additional StartListening call:

private static string StartServer()
{
    TcpChannel serverChannel = new TcpChannel(0);
     ChannelServices.RegisterChannel(serverChannel, false);
     RemotingConfiguration.RegisterWellKnownServiceType(typeof(MyHost), "MyHost",
                                                        WellKnownObjectMode.Singleton);
     return ((ChannelDataStore)serverChannel.ChannelData).ChannelUris[0];
}

Notes

• StartListening is a method of the IChannelReceiver interface and is also implemented by the other channels in .Net Remoting: IpcChannel and HttpChannel. However, these channels do not suffer from this behavior: calling StartListening on an already listening IpcChannel or HttpChannel doesn’t do anything.
• StartListening has its own place as a way to resume listening on a channel that is not listening. In other words, it is safe to call StartListening on a channel on which StopListening had been called previously.

In this post, I’ll try to (hopefully) bring some clarity to the subject.

Background

When a client calls a COM activation API (CoGetClassObject, CoCreateInstanceEx, CoGetInstanceFromFile, CoGetInstanceFromIStorage, IMoniker::BindToObject) and the component to be activated is out-of-process, several things happen.

The COM runtime (ole32.dll or combase.dll, running in the process that called the COM activation API) contacts the local RpcSs service (display name “Remote Procedure Call (RPC)”).

RpcSs determines if the component should be activated remotely. If so, the local RpcSs service forwards the request to the RpcSs service of the remote machine.

If not, RpcSs determines if the process that hosts that COM object is already running (RpcSs keeps internal data structures for every running DCOM server). If it is, it uses its endpoint to send the activation request to the process.

If the DCOM Server is not running, RpcSs sends the request to the local DcomLaunch service (display name “DCOM Server Process Launcher”) to execute the DCOM server that will host the desired component. DcomLaunch uses the CreateProcessXxx() APIs, or StartService() if the DCOM server has been configured to run as a service.

Note: DcomLaunch exists for security reasons: the RpcSs service runs under the “Network Service” account. This account does not have all the required permissions to create processes with different identities. Therefore, it defers these operations to DcomLaunch, that runs under the “Local System” account.

A DCOM Server can be a DCOM EXE server or a surrogate, including a COM+ server application. RpcSs first looks up the to-be-activated CLSID in the COM+ catalog. If it is not in the COM+ catalog, RpcSss searches the registry. Through these searches, RpcSs ultimately knows the name of the executable that should host the to-be-activated component.

Unlike COM server DLLs, which export the function DllGetClassObject to allow clients to get the class factories of the components hosted in the DLL, COM EXE servers must explicitly register their class factories by calling CoRegisterClassObject for each component it hosts. The RpcSs service maintains a local table, binding CLSIDs to running processes. The function CoRegisterClassObject() connects to the local RpcSs to add an entry to the table.

Note: the server can also call CoRegisterClassObject() using the REGCLS_SUSPENDED flag for every component, then register them all with RpcSs with CoResumeClassObjects(). This is more efficient if the COM server hosts many components.

As you can see, several things happen during COM activation. Consequently, several things can potentially go wrong. The RpcSs and DcomLaunch services write events to the System event log when this happens. The event source of all these events is “DistributedCOM”. The event ID identifies what exactly went wrong.

In the next section, we are having a look at these events, explaining when, and under which circumstances, each of them occurs. In the last section, we’ll explain how to troubleshoot them.

Note: what is being said in the following applies to Windows 10. Other versions of Windows, in many respects, will behave in the same or a similar way.

Events

As said in the previous section, when a process calls a COM Activation API, the activation request is passed on to the local RpcSs service and, if the DCOM Server must be started, further on to the DcomLaunch service.

If the DCOM Server is configured to be run with the identity of the caller (Activate as Activator, or “The Launching User” in Component Services):

DcomLaunch will impersonate the caller of the COM Activation API, then call CreateProcessAsUser to create the DCOM Server process under that same identity. If CreateProcessAsUser() fails, this event log is created:

MessageId=10000 Severity=Error SymbolicName=EVENT_RPCSS_CREATEPROCESS_FAILURE 
Unable to start a DCOM Server: %3. 
The error:%n"%%%2"%nHappened while starting this command:%n%1 

If the DCOM Server is configured to be run with a specific identity (“This user” in Component Services):

\

DcomLaunch will first call LogonUserExExW to get the access token. If it fails, DcomLaunch logs this error:

MessageId=10004 Severity=Error SymbolicName= EVENT_RPCSS_RUNAS_CANT_LOGIN 
DCOM got error "%%%1" and was unable to logon %2\%3 
in order to run the server:%n%4 

Next, DcomLaunch calls CreateProcessAsUser to launch the process. If CreateProcessAsUser() fails, this event log is created:

MessageId=10001 Severity=Error SymbolicName= EVENT_RPCSS_RUNAS_CREATEPROCESS_FAILURE 
Unable to start a DCOM Server: %3 as %4/%5. 
The error:%n"%%%2"%nHappened while starting this command:%n%1 

If the DCOM Server is configured to run as a service, StartService is called to start the service if needed. If StartService() fails, this event log is created:

MessageId=10005 Severity=Error SymbolicName=EVENT_RPCSS_START_SERVICE_FAILURE 
DCOM got error "%%%1" attempting to start the service %2 with arguments "%3" 
in order to run the server:%n%4 

The error reported in the log is obtained by calling GetLastError(), if StartService() returns FALSE.

Note:if the service is disabled, StartService() will fail but the above event is not logged.

If the DCOM Server is configured as a service, and the service is running, but returned CO_E_SERVER_STOPPING when asked to activate a component (meaning that the service is being stopped), then RpcSs queries the service status to check if it eventually reaches the SERVICE_STOPPED or SERVICE_RUNNING status. If this does not happen within 4 minutes, the following event is logged:

MessageId=10029 Severity=Error SymbolicName= EVENT_RPCSS_STOP_SERVICE_FAILURE 
The activation of the CLSID %1 timed out waiting for the service %2 to stop. 
in order to run the server:%n%4 

In COM+, it is possible to configure the application to be started under a debugger:

With this configuration in place, DcomLaunch calls CreateProcessAsUser for the specified debugger. Should CreateProcessAsUser() fail, the following event is logged:

MessageId=10030 Severity=Error SymbolicName= EVENT_RPCSS_CREATEDEBUGGERPROCESS_FAILURE 
Unable to start a COM Server for debugging: %3. 
The error:%n"%%%2"%nHappened while starting this command:%n%1 

The %3 argument is the CLSID of the component that is being activated, whereas %1 represents the command line that was passed to CreateProcessAsUser() to launch the debugger.

If, on the other hand, the component is configured for activation on a remote machine:

the local RpcSs defers the activation to the remote RpcSs. In this case, the first step of the local RpcSs is to establish a connection (an RPC binding) with the remote RpcSs. The connection is tried in several ways, using cached and uncached RPC binding handles, using client-specified security (if the client provided it) or trying all the available authentication packages and, if all of them fail, trying to establish an unauthenticated connection.

If none of the above succeeds, this event is logged:

MessageId=10028 Severity=Error SymbolicName= EVENT_RPCSS_REMOTE_SIDE_UNAVAILABLE_WITH_CLIENT_INFO 
DCOM was unable to communicate with the computer %1 using any of the configured protocols; requested by PID %2 (%3) 

Note: in older versions of Windows, the event is 10009 (EVENT_RPCSS_REMOTE_SIDE_UNAVAILABLE). Unlike EVENT_RPCSS_REMOTE_SIDE_UNAVAILABLE_WITH_CLIENT_INFO, EVENT_RPCSS_REMOTE_SIDE_UNAVAILABLE does not contain the PID of the client process that called the COM activation API.

If the connection to the remote RpcSs succeeds, but the activation fails, the local RpcSs reports the failure using the events:

MessageId=10006 Severity=Error SymbolicName= EVENT_RPCSS_REMOTE_SIDE_ERROR 
DCOM got error "%%%1" from the computer %2 when attempting to 
activate the server:%n%3

MessageId=10008 Severity=Error SymbolicName= EVENT_RPCSS_REMOTE_SIDE_ERROR_WITH_FILE 
DCOM got error "%%%1" from the computer %2 when attempting to 
activate the server:%n%3 with file %4. 

If the previous steps succeed, the DCOM Server is started successfully. There is an additional, important step: the DCOM server (an executable, a service or the DLLHOST.EXE surrogate) must register its class factories by calling CoRegisterClassObject. RpcSs waits for this to happen within a period of 2 minutes, otherwise it logs the following event in the event log:

MessageId=10010 Severity=Error SymbolicName=EVENT_RPCSS_SERVER_START_TIMEOUT 
The server %1 did not register with DCOM within the required timeout.

Note: all the event logs reported above are subject to filtering: if ActivationFailureLoggingLevel is 2, or if it is 0 and the activation API is called with CLSCTX_NO_FAILURE_LOG, no entry is written to the event log. The default value is 0, and usually clients do not use CLSCTX_NO_FAILURE_LOG, so failures are logged by default.

Troubleshooting

The troubleshooting is heavily dependent on the event ID.

If the Event ID is

MessageId=10004 Severity=Error SymbolicName= EVENT_RPCSS_RUNAS_CANT_LOGIN 
DCOM got error "%%%1" and was unable to logon %2\%3 
in order to run the server:%n%4 

this means, as said in the previous section, that the DCOM Server is configured with RunAs identity, RpcSs called LogonUserExExW() for that identity, but it failed.

The error logged (%1) is the value returned by GetLastError(), and it gives additional information about what went wrong.

Additional troubleshooting steps include double-checking that the username and password configured for the DCOM Server’s identity are valid, and that the account has not been disabled. Beware, in particular, of expired passwords. The security event log (Security Audit) can be a valid help to further troubleshoot this issue.

A set of events indicate that the process creation failed:

MessageId=10000 Severity=Error SymbolicName=EVENT_RPCSS_CREATEPROCESS_FAILURE 
Unable to start a DCOM Server: %3. 
The error:%n"%%%2"%nHappened while starting this command:%n%1 

MessageId=10001 Severity=Error SymbolicName= EVENT_RPCSS_RUNAS_CREATEPROCESS_FAILURE 
Unable to start a DCOM Server: %3 as %4/%5. 
The error:%n"%%%2"%nHappened while starting this command:%n%1

MessageId=10005 Severity=Error SymbolicName=EVENT_RPCSS_START_SERVICE_FAILURE 
DCOM got error "%%%1" attempting to start the service %2 with arguments "%3" 
in order to run the server:%n%4 

These events mean that CreateProcessAsUser()/StartService() failed. Follow these steps to troubleshoot:

1. The event log reports the error. This is the value returned by GetLastError() after the CreateProcessAsUser()/StartService() APIs failed. Often the error gives a valuable hint at what the problem is (access denied, file not found, etc).
2. The command is reported in the event log. Verify that the executable is in the specified location. If the executable was deleted, or moved to a different location without being re-registered, RpcSs will pass the wrong path to CreateProcessAsUser(). Re-registering the DCOM Server fixes this problem.
3. Verify that the executable has all its required dependencies. Be aware that some dependencies might work with your logged-in user path, but might not work with the path of another account (including the System account).
4. Try launching the executable manually from the command line, or starting the service manually - if this is not working, you can investigate this directly.
5. Verify that the executable does not have an Image File Execution Options (IFEO) key. If it does have such a key, and it has a "Debugger" named value, verify that the debugger listed is on the system path. A common mistake is to enter the name of the debugger without the full path in the Debugger value, and the folder is not in the PATH environment variable. This will cause CreateProcessAsUser() call from DcomLaunch to fail, with GetLastError() returning ERROR_FILE_NOT_FOUND (2), which is reported in the event log.
6. If the server is configured with RunAs (“This user”) or Activate-As-Activator (“The launching user”), verify that this identity has access to the server executable, and all its dependencies. If not, the error reported in events 10000, 10001 and 10005 will be access denied (5) The caller of the activation API will receive an E_ACCESSDENIED return value.
7. If the DCOM Server is implemented as a service, additional considerations apply:
   • Make sure that the service is not disabled.
   • The service startup may have run into trouble. This is unlikely if you are using a surrogate or a service written with ATL, because these services have well-tested service startup code. The section Debugging a Service Application in the “Debugging Tools for Windows” help has information on how to debug the service startup.

If none of the above resolves the issue, it is possible to get more information by debugging RpcSs and DcomLaunch directly. This is risky, however, because they are key operating system processes. Debugging in the usual way (say, for instance, by using Visual Studio) will almost certainly bring to a hang of the machine, or a crash. So, debugging is usually done by using a debugger like cdb.exe (part of the Debugging Tools for Windows) that does not have a user interface, and by using a debugger script that drives the debugger, thus never blocking the debugged process. This is an advanced scenario, I don’t recommend doing it unless you are really a debugging expert. If things get to this point, you may also get in touch with Microsoft Support for additional assistance.

We discussed the error

MessageId=10029 Severity=Error SymbolicName= EVENT_RPCSS_STOP_SERVICE_FAILURE 
The activation of the CLSID %1 timed out waiting for the service %2 to stop. 
in order to run the server:%n%4 

in some detail in the previous section. The real cause of this error is a service that presumably hung while stopping. You can take a dump of the process while it is in this state, and analyze it with WinDbg (also part of the Debugging Tools for Windows).

Another set of events applies to remote activation failure. The most likely cause of this event:

MessageId=10028 Severity=Error SymbolicName= EVENT_RPCSS_REMOTE_SIDE_UNAVAILABLE_WITH_CLIENT_INFO 
DCOM was unable to communicate with the computer %1 using any of the configured protocols; requested by PID %2 (%3) 

is that the remote machine is unreachable. It could be no longer available, turned off, or disconnected from the network.

The event log reports the name of the remote computer, so you can double-check that it is reachable from the machine where the event is logged.

It is possible that this event occurs because of a COM activation that is no longer needed or wanted. For instance, the destination machine may have been decommissioned and replaced with a machine having a different name. To modify the identification of the remote machine for the COM activation, let’s first keep in mind that this information can be specified either declaratively in Component Services, as shown in the picture in the previous section, or programmatically, by providing in the COSERVERINFO structure in the COM Activation API. Note that the event does not provide the CLSID of the component that we are trying to activate.

The events

MessageId=10006 Severity=Error SymbolicName= EVENT_RPCSS_REMOTE_SIDE_ERROR 
DCOM got error "%%%1" from the computer %2 when attempting to 
activate the server:%n%3 

MessageId=10008 Severity=Error SymbolicName= EVENT_RPCSS_REMOTE_SIDE_ERROR_WITH_FILE 
DCOM got error "%%%1" from the computer %2 when attempting to 
activate the server:%n%3 with file %4. 

indicate a remote activation failure. This means that the connection to the remote RpcSs could be established successfully, however the activation request itself, issued by the remote RpcSs, failed.

Note that, in this case, the remote machine may or may not log an event. For instance, if the activation failure on the remote machine is caused by the CLSID not being registered, there won’t be any corresponding event logged on the remote machine. If, on the other hand, the component is registered on the remote machine, but the executable is not found, the remote machine will log an event. In this case, the combination of the local and remote event contribute to give the complete picture. For instance:

Local:

Log Name: System 
Source: Microsoft-Windows-DistributedCOM 
Date: 4/12/2017 12:05:14 PM 
Event ID: 10006 
Task Category: None 
Level: Error 
Keywords: Classic 
User: Xxxx 
Computer: Yyyy 
Description: 
DCOM got error "2147942402" from the computer Zzzz when attempting to activate the server: 
{02ACA2A3-51F7-48FD-9246-5D0A84102414} 

Remote:

Log Name: System 
Source: Microsoft-Windows-DistributedCOM 
Date: 4/12/2017 12:05:14 PM 
Event ID: 10000 
Task Category: None 
Level: Error 
Keywords: Classic 
User: Xxxx 
Computer: Zzzz 
Description: 
Unable to start a DCOM Server: {02ACA2A3-51F7-48FD-9246-5D0A84102414}. The error: 
"2" 
Happened while starting this command: 
"D:\DCOMServer\x64\Release\DCOMServer.exe" -Embedding 

Last, the event

MessageId=10010 Severity=Error SymbolicName=EVENT_RPCSS_SERVER_START_TIMEOUT 
The server %1 did not register with DCOM within the required timeout. 

indicates that the DCOM Server was successfully started by DcomLaunch (CreateProcessAsUser()/StartService() succeeded), but it failed to register its class factories within 2 minutes. This is typically an indication of a problem happening in the startup of the DCOM Server.

If we rule out trivial errors in the code of the DCOM Server (for instance, having a code path that causes CoRegisterClassObject() not to be called), the issue can be of 3 types:

A. Crash at process startup

B. Deadlock at process startup

C. Macroscopic slowness at process startup

You can easily tell if we are in scenario A. by monitoring the lifetime of the DCOM server: we are in scenario A. if it starts up and terminates soon after. You can use the Task Manager or a tool like Process Explorer to determine this. Scenario A. can be further troubleshot by using a tool like Windows Error Reporting or ProcDump or another debugger specified as postmortem debugger, that takes a dump of the process when the crash occurs.

If, on the other hand, the DCOM Server stays alive until the event 10010 is logged, that means that we are in scenarios B. or C. Keep in mind that, after logging the 10010 event log, RpcSs kills the process (except if the DCOM Server runs as a service), if it hasn’t already died. RpcSs does this for a very good reason: by killing the process, the next COM activation request for the same CLSID, or a different CLSID hosted in the same DCOM Server, will cause a new process to be created, instead of directing the call to a running process that presumably hung. If the issue is a “once in a while” one, this makes it much more likely for the next activation request to succeed. However, you need to keep this in mind, when debugging the DCOM Server startup: if you attach a debugger to the process, the debuggee will likely be killed while you are debugging! A better approach in this case is to take a dump of the process in the time interval from the process startup until the DCOM event 10010 is logged.

You can take the memory dump with Task Manager:

Whatever the scenario A., B. or C. above, you end up with a user-mode dump of the DCOM Server. This can be analyzed with a debugger like WinDbg to find out the cause of the crash or the hang.]]> https://docs.microsoft.com/archive/blogs/carlos/side-by-side-execution-of-workflow-services-step-by-step-example Wed, 16 Dec 2015 07:44:00 GMT https://blogs.msdn.microsoft.com/carlos/2015/12/16/side-by-side-execution-of-workflow-services-step-by-step-example/ Introduction

In this blog post, we go through a complete example of a workflow service that handles multiple versions.

The MSDN Documentation covers this topic, and a sample is available in the Samples section of MSDN. In this post we are going to cover the topic step-by-step, building a complete sample from scratch. We will also try to emphasize the relevant pieces and to provide a motivation for them. We will focus on IIS/WAS-hosted workflow services, even though we will also briefly touch on the underlying API that is available to self-hosted workflow services. Last, we will cover the more advanced scenario of changes that extend outside the workflow definition itself, to activities used by the workflow.

Note: the step-by-step procedure is relative to Visual Studio 2015, the current version as of this writing. It is possible, though not guaranteed, that the same steps, possibly with minor adjustments, also work with other Visual Studio versions. Since SxS versioning is a new feature of WF4.5, the .Net Framework must be 4.5 or higher.

The steps are highlighted in yellow throughout the post.

Defining Side-by-Side Execution

Workflows (including workflow services) can be long-running. With long-running workflows, you may need to update the structure of a workflow while some instances are running. This poses the problem of what happens to the running instances.

In WF4.0, you do not have much choice: it is up to you to maintain the new and old definition at different endpoints, so the client has to explicitly decide which version to use. This obviously creates tight coupling between clients and the service.

WF4.5 addressed this lack of flexibility by providing two options:

• Side-by-side execution
• Dynamic update

Side-by-side execution is defined as follows:

• all the existing instances will continue to run, until completion, using the original workflow definition (that is, the definition that was current when the workflow instance started execution)
• new instances start execution using the most current workflow definition.

Dynamic update, on the other hand, implies the dynamic update of the running instances, so to migrate them to the new definition. If the dynamic update completes successfully for all the running instances, it is not necessary to keep multiple versions, because all instances (existing and new) will use the most recent version at this point.

In this post we focus on side-by-side execution only. This is the easiest and most common scenario.

Creating the Service

We start by creating the workflow service from the default template. As we’ll see, several additions are necessary before we can create a working side-by-side example. Nonetheless, starting with the default template is much faster than building everything from scratch.

To create the service:

• Open Visual Studio 2015
• Select the File | New | Project menu item
• In the dialog box, in the left pane, select Visual C# | Workflow
• Select WCF Workflow Service Application
• Give a name to the project (for instance, SxSWfSvc)

Note: you may want to open Visual Studio as Administrator. This is not required for the steps above, but it will make it possible to run the service under the debugger. Without administrative privileges, the service won’t be able to open the endpoint to listen for incoming requests.

Note: the default project configuration is such that, when running the project, it will open the URL to the currently selected document in the project (see Project Properties, Web tab, Start Action: it is set to Current Page). If anything other than Service1.xamlx is selected (for instance, web.,config), we won’t get the expected behavior. To fix this, change this setting: in Start Action, select Specific Page and set it to Service1.xamlx.

This service is already operational. You can double-check this by running the project in the debugger (F5). This fires up WcfTestClient; use it to execute the GetData operation and check that it completes successfully:

Adding a Second Operation

At the moment, our service has a single operation. Once a client calls the operation, the service completes execution. This service cannot be a long-running service. We need a service with at least two operations, in sequence. The first operation starts the service. Once the operation completes, the workflow service continues to run and is idle. When the client calls the second operation on the same workflow instance, the service completes execution. This way, the lifetime of the service is entirely in the hands of the clients, and workflow services can be as long-running as the clients wish.

In our case, the Message Exchange Pattern (MEP) between the client and the service, once we have added the second operation, will be like this:

InstanceId is the identifier (a GUID) of the running workflow instance. Note that this is just for the sake of this sample, a real-life workflow can return any business-related data.

To add a second operation:

• Drag and Drop a ReceiveAndSendReply “activity” to the workflow, at the end of the workflow

This is enough to add a second operation, however we also take the chance to do some cleanup, fix-up and cosmetic changes:

• In the Variables, rename __handle1 to SecondRequestResponse and chance its scope to “Sequential Service”
• Also in the Variables, rename handle to FirstRequestResponse. Ignore the validation error for now.
• Also in Variables, remove data, as we won’t use it anymore.
• Also in Variables, define a new variable at Sequential Service scope, of type System.Guid, and name it InstanceId
• Also in Variables, define a new variable at Sequential Service scope, of type string, and name it sInstanceId
• Change the display name of the Receive activities to ReceiveFirstOp and ReceiveSecondOp, respectively
• Change the display name of the Send activities to SendFirstOp and SendSecondOp, respectively
• Drag and Drop ReceiveSecondOp and SendSecondOp outside of their Sequence activity, directly below SendFirstOp
• Remove Sequence, which is empty at this point
• Change SendFirstOp: set Content to sInstanceId
• Change ReceiveFirstOp: set OperationName to StartWf and remove data from the Content. In CorrelationIntializers, set FirstRequestResponse instead of handle. Validation errors should disappear at this point.
• Change ReceiveSecondOp: set OperationName to ContinueWf and Content to sInstanceId
• Change SendSecondOp: set Content to “Done with " + sInstanceId.

FirstRequestResponse needs to return the InstanceId to the client, so we need to retrieve it. This information is available in the activity context, so the easiest way to retrieve it is by means of a code activity:

• Add a class to the project, name it WfInstanceId and implement it this way:

public class WfInstanceId: CodeActivity

{

    public OutArgument<Guid> InstanceId

    {

        get; set;

    }

    protected override void Execute(CodeActivityContext context)

    {

        InstanceId.Set(context, context.WorkflowInstanceId);

    }

}

Note: mind to make the class public, otherwise the activity won’t show up in the Toolbox in the next steps.

• Build the project (necessary for the WfInstanceId activity to show up in the Toolbox)
• Drag and Drop the WfInstanceId activity from the Toolbox to after ReceiveFirstOp and before SendFirstOp
• Set the InstanceId property of WfInstanceId to the InstanceId variable
• Drag and Drop an Assign activity from the Toolbox to after WfInstanceId. Assign to sInstanceId the value “InstanceId.ToString()”

This is how the workflow should look like at this point:

Adding Persistence

Though this is not a strict requirement, long-running workflows usually don’t stay in memory for their entire lifetime: they are persisted and unloaded when appropriate (typically, when they are idle, that is when they are waiting for some external event like an incoming message or an expired timer to occur, before resuming execution).

Persistence adds the following benefits:

• reliability: if the host crashes without having ever persisted a workflow instance, the instance state is lost. If, on the other hand, the workflow instance has been persisted, it can be resumed from its last persistence point.
• scalability: if thousands or workflows are executing at the same time (which is well possible, if workflows are long-running), persisting and unloading idle workflows decreases the memory usage and increases scalability. Scalability is further increased by the possibility to persist and unload from one machine and reload from a different machine.

Adding support for persistence is straightforward and can be done declaratively in the configuration file. In addition, we also configure the workflow to be persisted whenever it reaches an idle point:

• add the SqlWorkflowInstanceStore and WorklfowIdle behaviors to web.config:

<system.serviceModel>

  <behaviors>

    <serviceBehaviors>

      <behavior>

        <sqlWorkflowInstanceStore connectionString="Initial Catalog=WorkflowInstanceStore;Server=(local);Integrated Security=true"/>

        <workflowIdle timeToUnload="0:00:0" timeToPersist="0:00:0"/>

      </behavior>

    </serviceBehaviors>

  </behaviors>

 </system.serviceModel>

Configuring Correlation

Let’s try the sample. Run the project, use WcfTestClient to execute, in the correct sequence, the operations StartWf and ContinueWf. Make sure to copy the instance id, output of StartWf, to the input of ContinueWf (without “”).

When you execute the ContinueWf project, you should get this error message in WcfTestClient:

Why is that? The reason has to do with how correlation is configured for this workflow.

You may recall from the previous steps that we have two variables of type CorrelationHandle in our workflow: FirstRequestResponse and SecondRequestResponse. These correlation handles are initialized with a Request-reply correlation initializer (see the CorrelationInitializers property of ReceiveFirstOp and ReceiveSecondOp). They are used to correlate each Receive activity to its corresponding SendReply activity (or activities).

However, we don’t have anything that relates the first operation to the second operation. In other words, we need something that, when the client calls the second operation, is able to identify to which running workflow instance this operation is directed.

There are two types of correlation that can be used for this purpose: context-exchange correlation and content-based correlation. This MSDN topic and its subtopics have all the details. We will be using content-based correlation in this case, because the workflow can be long running. The lifetime of a long-running workflow should not be constrained by the lifetime of the client that initiated it (in other words, it should be possible for one client to start the workflow, and for other clients to continue its execution). Since a context, established by context-exchange correlation, is limited to the lifetime of the client, it is not suitable for our needs.

Content-based correlation uses values (called instance keys) contained in the messages exchanged by client and service, that uniquely identify a workflow instance. In our MEP described above, this role can be played by the InstanceId. Therefore, we will configure content-based correlation using the InstanceId as the key. To do this, follow these steps:

• Add a variable named InstanceCorrelation of type CorrelationHandle, at Sequential Service scope
• Set the CorrelationInitializers property of SendFirstOp: type InstanceCorrelation on the left, then select “Query correlation initializer” and select Content: String in the XPath query
• Set the CorrelatesOn property of ReceiveSecondOp: set CorrelatesWith to InstanceCorrelation, and select Content: String in the XPath query

The steps above look somewhat esoteric, but in fact they are pretty simple: we are basically specifying that the key that uniquely identifies the message is the InstanceId contained, in string form, in the response of the first operation and in the request of the second operation.

Let’s now test that this fixed the previous FaultException: run with F5, execute the first operation, copy the output GUID and paste it into the input of the ContinueWf operation (make sure not to include the “”). This time everything should work and you should get “Done with <GUID>” in the Response of the ContinueWf operation.

Let’s further test the effect of content-based correlation: as before, execute StartWf. Copy the returned GUID. However, this time after pasting the GUID in ContinueWf, modify it so that it does not match the one returned by StartWf and execute.

You should get this exception:

System.ServiceModel.FaultException was unhandled
Message: An exception of type 'System.ServiceModel.FaultException' occurred in mscorlib.dll and wasn't handled before a managed/native boundary
Additional information: The execution of an InstancePersistenceCommand was interrupted because the instance key 'b4c6f11b-a465-87ce-fe6e-7cf3d2558b6c' was not associated to an instance. This can occur because the instance or key has been cleaned up, or because the key is invalid. The key may be invalid if the message it was generated from was sent at the wrong time or contained incorrect correlation data.

The key that we provided is invalid, because there isn’t any running workflow instance with that instance id, hence the exception.

Note: if you query the InstancesTable table of the persistence database, you should find an instance with the GUID used in the last test: since we failed to execute the second operation, that workflow instance is still running, persisted in the database.

Adding Support for Multiple Versions

After sorting out all the previous steps, we are now ready to implement side-by-side execution. The steps are pretty easy, but let’s first look at the api provided at WF Runtime level since WF4.5, as this helps understand what happens in IIS/WAS-hosted workflows.

WorkflowService in WF4.5 has a new property, DefinitionIdentity of type WorkflowIdentity, which identifies a particular version of a workflow service definition. In addition, WorkflowServiceHost has a SupportedVersions property, which is a collection of WorkflowService instances.

When explicitly using WorkflowServiceHost (self-hosting), a host that supports multiple versions side-by-side would use the following code:

WorkflowService initialService = new WorkflowService

{    

    Name = "MyWorkflowService",

    Body = new MyWorkflowService1(),

    DefinitionIdentity = new WorkflowIdentity("Initial Version", new Version(1, 0, 0, 0), null)

};

WorkflowService updatedService = new WorkflowService

{

   Name = "MyWorkflowService",

   Body = new MyWorkflowService2(),

   DefinitionIdentity = new WorkflowIdentity("Updated Version", new Version(2, 0, 0, 0), null)

};

WorkflowServiceHost sh = new WorkflowServiceHost(updatedService);

sh.SupportedVersions.Add(initialService);

This host will implement SxS versioning, in that

• when a new workflow is activated, version 2.0.0.0 is used
• when a request directed at an existing instance arrives, the correct workflow definition will be used, if it is 1.0.0.0 or 2.0.0.0.

For IIS/WAS-hosted workflow services, this same effect can be achieved by using a well-defined naming convention for workflow services and the folders that contain them. Specifically:

• the .xamlx file at the URL used by the client is the “main version”, equivalent to the one used as an argument of the WorkflowServiceHost constructor in the code above
• all the .xamlx files placed under subfolders of App_Code, named after the workflow service itself, are “supported versions”, equivalent to those added to the SupportedVersions collection in the code above.

The DefnitionIdentity property of WorkflowService can be set directly in the workflow designer.

In our sample, we opt for a change to the InstanceId that is used to uniquely identify the workflow. Instead of the GUID, we want to use the syntax InstanceId: GUID. Before making the change, we run StartWf and get the Instance ID back. This is to ensure that, after making the change, we’ll have an instance running with the previous workflow definition.

In order to support SxS execution in our sample:

• Set the DefinitionIdentity property of Service1.xamlx: set Name to “Service1” and Version to 1.0.0.0. Leave Package empty.
• Create a subfolder called App_Code
• Create a subfolder of App_Code, named Service1
• Copy Service1.xamlx to the Service1 subfolder, possibly changing the file name (for instance, Service1_v1.xamlx)
• Make changes to the top-level Service1.xamlx file: set Version in DefinitionIdentity to 2.0.0.0; set SendFirstOp’s Content to ‘“Instance Id: “ + sInstanceId; set SendSecondOp’s Content to "V2: Done with " + sInstanceId
• Build and run
• Execute StartWf. This will start a new workflow that uses version 2.0.0.0, so you should get a response like “Instance Id: <GUID>”
• Copy the string and paste (without quotes) in the Request of ContinueWf. You should get the Response: “V2: Done with Instance Id: <GUID>”
• Execute ContinueWf using this time the GUID returned by StartWf before we introduced versioning. You should get the Response “Done with Instance Id: <GUID>”. This shows that this workflow instance continued execution using the original workflow definition, thus achieving the desired SxS versioning behavior.

Constraints of Multiple Versions

You may have noticed that, when upgrading our workflow service from version 1.0.0.0 to version 2.0.0.0, we haven’t changed the MEP between client and service. Note that the client code does not change and the choice of which version to use is taken at runtime on the service side. Any change to the MEP between client and service, for instance

• Changing the names of the operations
• Changing the number or type of the arguments of the operations
• Adding / removing operations to the MEP
• Changing the type of the operation from Request/Response to OneWay or vice-versa

For the sake of completeness, let’s see what happens if we change the MEP:

• Under App_Code\Service1, copy Service1_v1.xamlx to Service1_v15.xamlx
• Change DefinitionIdentity for Service1_V15.xamlx: set Version to 1.5.0.0
• Modify SendFirstOp of Service1_V15.xamlx: set Content to InstanceId instead of sInstanceId
• Build and run.

When WcfTestClient starts, it should display an error message. If you look at it in Html View, you should see an error message like this:

Exception loading supported version 'App_Code\Service1\Service1_v15.xamlx': Two SendReply objects with same ServiceContractName and OperationName 'StartWf' have different ValueType.

Before going forward, remove Service1_v15.xamlx, otherwise the service won’t start.

Updating Code Activities

So far in our example, the changes were relative to the .xamlx file only. Workflows, however, are made of activities, and some of them can be custom activities, which in turn may also use custom assemblies in their implementation. When it comes to modifying a workflow definition, therefore, the changes are not necessarily restricted to the .xamlx workflow service; they may also affect custom assemblies (eventually the same assembly where .xamlx files are located).

Note: the following considerations on assembly version handling apply to code activities and other custom assemblies as well.

In order to exemplify the concept, let’s now make a variation to our previous change: instead of changing the returned string by editing the Content of SendFirstOp, we change the implementation of the WfInstanceId activity to return a string with the new syntax. This also requires changing the type of OutArgument of WfInstanceId, from System.Guid to String.

This change requires modification to both the .xamlx file and the compiled assembly, where WfInstanceId is defined. Mind that, if we want to support SxS for the workflow service, we need to keep both versions of the assembly: running instances that use the previous version will still need access to the previous version of WfInstanceId.

In .Net it is possible to keep multiple versions of an assembly in this way:

• give different assembly version to the assemblies
• put the assemblies in the GAC

Note: assembly version is different from the file version. In .Net, assembly version is set with the AssemblyVersion attribute, the file version is set with the AssemblyFileVersion attribute.

Note: in order to put the assemblies in the GAC it is also necessary to give them a strong name.

All this is simplified if we factor out the custom activity in a separate assembly, so let’s do it first:

• Add a new project to the solution, of type class library. We can call it ActivityLibrary (but feel free to choose a different name)
• Remove Class1.cs from the project, as we won’t use it
• Move WfInstanceId.cs from the previous project to the new project. You may want to change the namespace for the WfInstanceId activity. Also fix-up assembly references (add System.Activities).

Now we need to give a strong name to the assembly built out of this new project, and to put the assembly in the GAC at the end of each successful build:

• In the Project Properties of ActivityLibrary, in the Signing tab, check “Sign the assembly” and choose a .snk file (or create new, if you don’t have one already)
• In the Project Properties of ActivityLibrary, in the Build Events tab, add a Post-build event “gacutil.exe –i $(TargetPath)” (you’ll need to use the full path to gacutil.exe, if it is not in the PATH environment variable)

If you build the ActivityLibrary project, you should see that the assembly is now in the GAC (look under %WINDIR%\Microsoft.NET\assembly).

The assembly we have just built has version 1.0.0.0, this is determined by the AssemblyVersion attribute in AssemblyInfo.cs. Now let’s build version 2.0.0.0 of this assembly, with the updated WfInstanceId activity:

• Set the AssemblyVersion attribute to 2.0.0.0 in AssemblyInfo.cs
• Modify the WfInstanceId activity in this way:

public class WfInstanceId: CodeActivity

{

    public OutArgument<string> InstanceId

    {

        get; set;

    }

    protected override void Execute(CodeActivityContext context)

    {

        InstanceId.Set(context, "Instance Id: " + context.WorkflowInstanceId.ToString());

    }

}

• Build the solution (including the SxSWfSvc project). If you look at the GAC now, you should see that both version 1.0.0.0 and version 2.0.0.0 of the assembly are present.

Let’s recall that different versions of our workflow service will need to use different versions of the WfInstanceId activity. Let’s open the two .xamlx files in the designer. You should see something like this:

The reason of the error is that the referenced activity is still the one contained in SxSSvcWf, which is no longer present. At the same time, in the toolbox you will see the new WfInstanceId activity under the ActivityLibrary category. For both .xamlx files, let’s fix the error:

• Remove the old WfInstanceId activity (the red box)
• Drag&Drop the new WfInstanceId activity in the same position

We also need to bind the InstanceId argument of the WfInstanceId activity. You’ll notice, if you try to bind it, that for both XAMLX files the InstanceId argument appears to be of type String:

In other words, both versions of the workflow service are now using the WfInstanceId activity contained in version 2.0.0.0 of the ActivityLibrary assembly, This is not what we want, and it is happening because the activity in the toolbox is version 2.0.0.0. Let’s make the following changes:

• Remove the WfInstanceId activity from the Toolbox
• Right-click on the ActivityLibrary category in the Toolbox and select “Choose Items…”
• In the dialog box, click the Browse button and select ActivityLibrary.dll version 1.0.0.0 and ActivityLibrary version 2.0.0.0 from the GAC, as shown below:

When you click Ok, you should get a cryptic message box with this message:

The following controls were successfully added to the toolbox but are not enabled in the active designer: WfInstanceId

This message means that we do have both activities in the toolbox, but only one of them is shown when the current workflow service is open. If we hover on the WfInstanceId activity shown in the Toolbox, we find out that it is version 2.0.0.0. If we open the other version of the workflow service, the same thing happens. So our workflow services are still referencing version 2.0.0.0 of the ActivityLibrary assembly.

Let’s have a look at how ActivityLibrary is referenced by our workflow services. In order to do this, we need to switch to the XAML view of the workflow services. Right-click on Service1.xamlx and select “View Code”. Near the beginning of the xamlx file you should see something like this:

xmlns:a="clr-namespace:ActivityLibrary;assembly=ActivityLibrary"

In other words. the assembly reference is qualified only by name, not by the fully qualified assembly name, including version and public key token. This is how the workflow designer adds assembly references automatically, and it has its own advantages in some scenarios. If there are multiple versions in the GAC, the latest is loaded. This explains why we could only see version 2.0.0.0 in the Toolbox.

The good thing is that you can manually modify the default, and fully qualify an assembly reference. Since we need to reference different versions of the assembly from our workflow services, do the following:

• open the top-level Service1.xamlx and replace the assembly reference with:

xmlns:a="clr-namespace:ActivityLibrary;assembly=ActivityLibrary, Version=2.0.0.0, Culture=neutral, PublicKeyToken=4a41ef8fd7501054"

• open the xaml under App_Code and replace the assembly reference with:

xmlns:a="clr-namespace:ActivityLibrary;assembly=ActivityLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=4a41ef8fd7501054"

Note: The PublicKeyToken depends on the signing key and will be different in your case, You can find the full assembly reference using ILDASM, ILSpy or another disassembly tool.

After saving the .xamlx files, open them under the designer. If you try to bind the InstanceId argument of WfInstanceId, you should find that each workflow service is referencing its own version. So in the workflow service under App_Code you should see that the argument is of type Guid:

Now let’s complete the binding. For the workflow service 1.0.0.0:

• Bind InstanceId to the InstanceId variable, as before

For the workflow service version 2.0.0.0:

• Bind InstanceId to the sInstanceId variable
• Remove the Assign activity that follows the WfInstanceId activity in the workflow

If you try this time, you should see that both new workflows and existing workflows can run successfully.

SxSWfSvc.zip

WF 4.5 added Versioning and Dynamic Updates to workflows.

The dynamic update process consists in 2 main steps:

1. Defining the update, in terms of changes to the workflow definition. The output of this step is an Update Map
2. Applying the Update Map to persisted workflow instances

Step A. above takes place in 3 substeps:

1. Calling DynamicUpdateServices.PrepareForUpdate(Activity), where activity is the root activity of the workflow definition
2. Making in-memory changes to the workflow definition
3. Calling DynamicUpdateServices.CreateUpdateMap(Activity). This creates an update map, which is typically persisted, to be used sometime later to carry out step B. above.

Under the hood

Steps 1. – 3. above must be applied to the same in-memory workflow definition. This is because DynamicUpdateServices.PrepareForUpdate(activity) prepares that specific in-memory workflow definition for update, so the following call to CreateUpdateMap() must happen on the same in-memory instance.

PrepareForUpdate() annotates the in-memory workflow definition with information that will be used at a later time, when CreateUpdateMap() is called, to compute the delta. This is logically equivalent to creating an internal cloned workflow definition.

Note: PrepareForUpdate() and CreateUpdateMap() have overloads that take an ActivityBuilder as an argument, instead of an Activity. This simplifies the usage in conjunction with workflow definitions loaded from XAML (XamlServices.Load() returns an ActivityBuilder object, not an Activity), but it does not change the requirement that changes be applied to the in-memory workflow definition.

The Code Approach

Let’s focus now on step A.2 above, the in-memory changes to the workflow definition.

The easiest approach to the in-memory changes is to hard-code the changes in code. This link exemplifies this process. See, specifically, the “To update StateMachineNumberGuessWorkflow”, “To update FlowchartNumberGuessWorkflow” and | To update SequentialNumberGuessWorkflow” sections.

This approach works just fine. However, by hard-coding the changes into the program, it

• requires a different program for each new change
• requires a programmer to make the change, instead of a business owner
• may require a complex and hard-to-read sequence of statements in order to make a simple change to the workflow definition. This is especially true when the changes are made deep into the hierarchy of activities

In order to overcome these limitations, the changes would have to be made through the Workflow Designer, instead of being hard-coded. The requirement that the changes be made to the in-memory workflow definition rules out the Workflow Designer used in Visual Studio however: the WF Designer used in Visual Studio loads a workflow from a XAML file and saves the change to a XAML file, so it is not usable to make in-memory changes to a workflow definition.

The Re-hosted Workflow Designer Approach

The Workflow Designer, thankfully, is a reusable component that can be hosted in any process. Visual Studio just happens to be one host of Workflow Designer. By re-hosting the Workflow Designer in a custom host, we may be able to allow in-memory changes to the workflow definition through the Workflow Designer.

The Sample Code

The sample code attached to this post is general-purpose: the input is a workflow in XAML and the output, after the user makes changes to the workflow definition in the designer, are:

• the XAML file of the modified workflow
• the update map (XML file)

To use the sample:

• Load a workflow from the FIle…Open Workflow Definition menu item. DynamicUpdateServices.PrepareForUpdate() is called at this stage.
• Make the changes to the workflow definition in the designer. This includes adding activities, modifying existing activities, adding/removing variables and arguments.
• Save the workflow and create the update map using the File…Save and Create Update Map menu item. First, you can save the workflow definition to a .XAML file. Then, if you choose to save the update map, DynamicUpdateServices.CreateUpdateMap() is called and the update map is saved to an XML file.

This is how the program looks like, when a workflow definition is loaded:

A word of caution

A re-hosted Workflow Designer does not always offer the same user experience of the Workflow Designer in Visual Studio, because the Workflow Designer can be configured in many different ways.

For instance, the Services and Items of the Editing Context may be different, or configured differently. Also, a re-hosted Workflow Designer has some limitations. As far as dynamic update of workflows goes, though, these limitations should not be a roadblock.

You’ll also notice that the behavior of the Toolbox in the sample differs from that of Visual Studio:

• at startup, a pre-defined set of common activities is loaded in the Toolbox, grouped into a set of categories
• when a workflow definition is loaded, the activities of the workflow are added to a new category called Auto, displayed at the top of the toolbox
• it is possible to load additional activities by using the File | Add Activities in Assembly… menu item. All the activities in that assembly are added to a new category, named after the assembly, displayed at the bottom of the toolbox. You may want to load the System.Activities.dll assembly to see a broad range of activities (more than the Visual Studio toolbox shows)
• you can remove an entire category or an activity from the toolbox by right-clicking on them and selecting Remove

The sample provided here is not production-ready code: error handling is minimal, it does not have tracing or logging, and it has not been extensively tested.

All this said :-), if you find any issue with the sample, please let me know.

Enjoy!

UpdateWithDesigner.zip

The SqlWorkflowInstanceStore class in WF4 uses a Sql Server database for persistence. See this post for more details on how you can create the schema and the logic for the persistence database.

The database stores the serialized form of workflow instances, along with lock and key information.

Database clean-up

You may need to restart from a clean database from time to time. This can be a consequence of some testing, that caused the accumulation of a number of persisted instances that you do not want to, or can’t, continue to execute. In these cases, you may decide to remove the database altogether, create a new one and re-create its schema and logic.

However, there may be scenarios where deleting and re-creating the database is not convenient, for one of these reasons:

• You changed the permissions in the database. The typical case is when the client process is the IIS/WAS worker process W3WP.EXE, and you added a user for its identity (NETWORK SERVICE, for instance) and appropriate role membership for it.
• You need to act quickly, possibly because this is a production environment that ended up in an unexpected state and you want to quickly restore a working environment.
• You are sharing the persistence DB with “something else”. For instance, the AppFabric Monitoring and AppFabric Persistence schemas (a superset of the WF4 Persistence schema) can coexist in the same database.

In these cases, you may prefer to simply clean up the existing database.

A few caveats apply:

• Cleaning up the persistence database may cause loss of data: if there are workflow instances currently persisted in the database, you won’t be able to reload them in memory at a later time, after cleaning up the persistence database.
• The clean up of the database should take place when all its users (all the applications that are using this database as the persistence store for workflows) are in a stopped state. Running processes that use workflows may make use of existing entries in the LockOwnersTable and would raise an exception if those entries are removed.
• The schema of the persistence database may change in future releases of WF. It is not guaranteed that this procedure will work with future releases of WF. The current release as of this writing is WF 4.5.

Clean up consists in truncating the contents of nearly all the persistence tables in the database, This is a stored procedure that you can use:

CREATE PROCEDURE [dbo].[DeleteAll] 
AS
 BEGIN
     SET NOCOUNT ON;
     SET TRANSACTION ISOLATION LEVEL READ COMMITTED
     SET XACT_ABORT ON;    

    BEGIN TRANSACTION

    TRUNCATE TABLE [System.Activities.DurableInstancing].[IdentityOwnerTable];
    TRUNCATE TABLE [System.Activities.DurableInstancing].[InstanceMetadataChangesTable];
    TRUNCATE TABLE [System.Activities.DurableInstancing].[InstancePromotedPropertiesTable];
    TRUNCATE TABLE [System.Activities.DurableInstancing].[KeysTable];
    TRUNCATE TABLE [System.Activities.DurableInstancing].[LockOwnersTable];
    TRUNCATE TABLE [System.Activities.DurableInstancing].[RunnableInstancesTable];
    TRUNCATE TABLE [System.Activities.DurableInstancing].[ServiceDeploymentsTable];
    TRUNCATE TABLE [System.Activities.DurableInstancing].[InstancesTable];

    COMMIT TRANSACTION
 END

Note: the table IdentityOwnerTable is part of the Workflow Persistence Schema since WF4.5. Therefore, if you are using WF4.0, the first TRUNCATE statement in the procedure above should be removed.

In the previous post, we looked at how multiple CLRs can be loaded in the same process (CLR InProc SxS).

In this post, we’ll build on the example from that post to look at how we can do debugging of processes that use multiple CLRs. We’ll focus on CLR4 with CLR2, because CLR 1.x has been largely replaced by new versions (though the same considerations should apply to CLR4 with CLR 1.x).

We’ll focus on the two most popular ways to debug managed processes: Visual Studio and WinDbg + the SOS debugger extension. Visual Studio has  friendlier user interface and is easier to use, WinDbg + SOS allows more in-depth debugging, and is especially versed towards dump analysis.

Visual Studio 2012

With reference to the sample code, if we start ConsoleApplication3 under the debugger, and we let it execute until both CLRs are loaded (Console.ReadKey() statement in Main()), everything seems to work fine as we debug.

If we look at the modules window, however, we see the following:

The modules in the window are assemblies loaded by the CLR2. ClassLibrary3.dll, loaded by the CLR4, is notably missing here.

If you set breakpoints inside ClassLibrary3.dll, for example in Class1.DoNothing()), the breakpoint won’t be hit. All these symptoms have the same common root: only the CLR2 debugger is active. This is because the process started as a CLR2 process (ConsoleApplication3 binds to CLR2) and, consequently, Visual Studio loaded the “right” CLR debugger.

If we attach Visual Studio to a running process, we do have a way to manually choose the Visual Studio debuggers, by using the Debug…Attach to Process menu item.

So we run the process again, outside of Visual Studio (Ctrl+F5), and we attach later on and select the debuggers. Note however that you can’t select both CLR2 and CLR4:

Note however that, once you attached to a process, you can’t further change the debugger during the same debugging session: the user interface of the Attach To Process dialog grays out the currently debugged process.

If we restart the process and attach using the CLR4 debugger this time, we have a different managed view of the debuggee. For instance, this is the set of managed modules:

Along the same lines: a breakpoint in ClassLibrary3.dll (using CLR4) will be hit, but a breakpoint in ConsoleApplication3.exe (using CLR2) will not.

Note: you may have noticed that mscorlib.dll shows up in the list of modules when the CLR2 is being debugged, and when CLR4 is being debugged. Note however that they are different modules: version and timestamp are different.

Note: you can also enable native debugging (step into native code, setting breakpoints on native code, etc.) by selecting the “Enable Native Code Debugging” check box in the Debug tab of the startup project (ConsoleApplication3 in this case). With this sample, this may be handy if you want to follow the thread of execution from ConsoleApplication3 to ATLProject1, down to Classlibrary3. With Visual Studio 2012, this works for 32-bit builds, not for 64-bit builds (mixed-mode debugging is not supported for 64-bit with earlier versions of the .Net Framework).

Exceptions

The same story applies to exceptions: only exceptions raised by a debugged CLR are recognized by Visual Studio. Since you can debug at most one CLR at a time, this means that you don’t have a way to break the debugger on every managed exception. This is a limitation especially if you are troubleshooting a complex issue and any exception can put you on the right track.

WinDbg with SOS

If we attach WinDbg to a running process using both CLR2 and CLR4, we’ll see that both CLR dlls are loaded:

0:008> lm v mclr
start             end                 module name
00007ffc`6e020000 00007ffc`6e9b8000   clr        (deferred)             
    Image path: C:\Windows\Microsoft.NET\Framework64\v4.0.30319\clr.dll
    Image name: clr.dll
    Timestamp:        Tue Aug 06 01:43:57 2013 (520038BD)
    CheckSum:         0099DECA
    ImageSize:        00998000
    File version:     4.0.30319.33440
    Product version:  4.0.30319.33440
    File flags:       8 (Mask 3F) Private
    File OS:          4 Unknown Win32
    File type:        2.0 Dll
    File date:        00000000.00000000
    Translations:     0409.04b0
    CompanyName:      Microsoft Corporation
    ProductName:      Microsoft® .NET Framework
    InternalName:     clr.dll
    OriginalFilename: clr.dll
    ProductVersion:   4.0.30319.33440
    FileVersion:      4.0.30319.33440 built by: FX45W81RTMREL
    PrivateBuild:     DDBLD106
    FileDescription:  Microsoft .NET Runtime Common Language Runtime - WorkStation
    LegalCopyright:   © Microsoft Corporation.  All rights reserved.
    Comments:         Flavor=Retail

0:008> lm v mmscorwks
start             end                 module name
00007ffc`72010000 00007ffc`729af000   mscorwks   (deferred)             
    Image path: C:\Windows\Microsoft.NET\Framework64\v2.0.50727\mscorwks.dll
    Image name: mscorwks.dll
    Timestamp:        Wed Aug 14 06:55:49 2013 (520B0DD5)
    CheckSum:         0098EB16
    ImageSize:        0099F000
    File version:     2.0.50727.7905
    Product version:  2.0.50727.7905
    File flags:       0 (Mask 3F)
    File OS:          4 Unknown Win32
    File type:        2.0 Dll
    File date:        00000000.00000000
    Translations:     0409.04b0
    CompanyName:      Microsoft Corporation
    ProductName:      Microsoft® .NET Framework
    InternalName:     mscorwks.dll
    OriginalFilename: mscorwks.dll
    ProductVersion:   2.0.50727.7905
    FileVersion:      2.0.50727.7905 (win9rel.050727-7900)
    FileDescription:  Microsoft .NET Runtime Common Language Runtime - WorkStation
    LegalCopyright:   © Microsoft Corporation.  All rights reserved.
    Comments:         Flavor=Retail

SOS is the debugger extension used by native debuggers like WinDbg to debug managed code. Each version of the CLR ships with its own SOS.dll (in the same folder of the CLR dll), and it can be loaded with the .loadby command (for user dumps coming from a different machine,  .loadby may not always work, depending on the path of the .Net Framework on the target machine and on the bitness of the target process, see this post for more details):

0:008> .loadby sos clr
0:008> .loadby sos mscorwks
0:008> .chain
...
Extension DLL chain:

    dbghelp: image 6.13.0015.1725, API 6.3.6, built Sat Feb 16 04:34:59 2013
        [path: C:\dbginternal\dbghelp.dll]
    ext: image 6.13.0015.1825, API 1.0.0, built Sat May 04 11:27:44 2013
        [path: C:\Users\carcolo\AppData\Local\DBG\ExtLibrary\x64\ext\6.13.15.1825\winext\ext.dll]
    exts: image 6.13.0015.1725, API 1.0.0, built Sat Feb 16 04:37:51 2013
        [path: C:\dbginternal\WINXP\exts.dll]
    uext: image 6.13.0015.1725, API 1.0.0, built Sat Feb 16 04:37:47 2013
        [path: C:\dbginternal\winext\uext.dll]
    ntsdexts: image 6.3.9321.0, API 1.0.0, built Sat Feb 16 04:37:58 2013
        [path: C:\dbginternal\WINXP\ntsdexts.dll]

However, once you start issuing commands, something strange happens (note that we are using the full path of the debugger extension, in order to distinguish SOS for CLR2 from SOS for CLR4:

0:008> !C:\Windows\Microsoft.NET\Framework64\v2.0.50727\sos.threads
ThreadCount: 2
UnstartedThread: 0
BackgroundThread: 1
PendingThread: 0
DeadThread: 0
Hosted Runtime: no
                                              PreEmptive                                                Lock
       ID OSID        ThreadOBJ     State   GC     GC Alloc Context                  Domain           Count APT Exception
   0    1 1d80 000000000118b750      a020 Enabled  00000000030e0160:00000000030e1fd0 0000000001181a80     0 MTA
   2    2 3008 0000000001199c80      b220 Enabled  0000000000000000:0000000000000000 0000000001181a80     0 MTA (Finalizer)

0:008> !C:\Windows\Microsoft.NET\Framework64\v4.0.30319\sos.threads
Failed to load data access DLL, 0x80004005
Verify that 1) you have a recent build of the debugger (6.2.14 or newer)
            2) the file mscordacwks.dll that matches your version of clr.dll is 
                in the version directory or on the symbol path
            3) or, if you are debugging a dump file, verify that the file 
                mscordacwks_<arch>_<arch>_<version>.dll is on your symbol path.
            4) you are debugging on supported cross platform architecture as 
                the dump file. For example, an ARM dump file must be debugged
                on an X86 or an ARM machine; an AMD64 dump file must be
                debugged on an AMD64 machine.

You can also run the debugger command .cordll to control the debugger's
load of mscordacwks.dll.  .cordll -ve -u -l will do a verbose reload.
If that succeeds, the SOS command should work on retry.

If you are debugging a minidump, you need to make sure that your executable
path is pointing to clr.dll as well.

0:008> .cordll-I clr -ve -u -l
Automatically loaded SOS Extension
CLRDLL: Loaded DLL C:\Windows\Microsoft.NET\Framework64\v4.0.30319\mscordacwks.dll
CLR DLL status: Loaded DLL C:\Windows\Microsoft.NET\Framework64\v4.0.30319\mscordacwks.dll

Good, we loaded the DAC dll for CLR4, so commands work now:

0:008> !C:\Windows\Microsoft.NET\Framework64\v4.0.30319\sos.threads
ThreadCount:      2
UnstartedThread:  0
BackgroundThread: 2
PendingThread:    0
DeadThread:       0
Hosted Runtime:   no
                                                                                                        Lock  
       ID OSID ThreadOBJ           State GC Mode     GC Alloc Context                  Domain           Count Apt Exception
   0    1 1d80 000000000120a360    28220 Preemptive  000000001C6D5308:000000001C6D5FD0 00000000011fd530 0     MTA 
   7    2 15b0 0000000001219060    2b220 Preemptive  0000000000000000:0000000000000000 00000000011fd530 0     MTA (Finalizer) 

Note the output of the !threads commands against CLR2 and CLR4: they reflect the different view that each CLR has on the process: thread 0 is known to both CLR2 and CLR4, because this thread has executed code in both. CLR2 also knows thread 2, which is unknown to CLR4. This is because this thread so far has executed CLR2 code only. Conversely, thread 7 has executed CLR4 code only.

Also note that, for thread 0, the thread object is different: 000000000118b750 for CLR2, 000000000120a360 for CLR4. This is because each CLR keeps its own runtime data structures, distinct from each other: therefore each CLR has its own thread object, both referencing the same OS thread. The same applies to other runtime data structures: AppDomains, Types, Method Tables, Method Descriptors, and so on.

If we enter again the !threads command for CLR2, however, we face the “unexpected”:

0:008> !C:\Windows\Microsoft.NET\Framework64\v2.0.50727\sos.threads
Failed to request ThreadStore

Loading the CLR4 DAC caused unload of the CLR2 DAC, hence the SOS commands directed at CLR2 no longer work. We can reload the CLR2 DAC manually:

0:008> .cordll -I mscorwks -ve -u -l
Automatically loaded SOS Extension
CLRDLL: Loaded DLL C:\Windows\Microsoft.NET\Framework64\v2.0.50727\mscordacwks.dll
CLR DLL status: Loaded DLL C:\Windows\Microsoft.NET\Framework64\v2.0.50727\mscordacwks.dll

This will make the SOS for CLR2 work, but the SOS for CLR4 will stop working.

The reason of this behavior is that only one DAC dll can be loaded in the debugger at a given time.

You can load the DAC that you need at a given time. For instance, with the CLR4 DAC loaded, the call stack of thread 0 looks like this:

0:000> kL
Child-SP          RetAddr           Call Site
00000000`0109e878 00007ffc`7b3d525e ntdll!ZwDeviceIoControlFile+0xa
00000000`0109e880 00007ffc`7b485400 KERNELBASE!ConsoleCallServerGeneric+0xe6
00000000`0109e9e0 00007ffc`7b49c318 KERNELBASE!GetConsoleInput+0x38820
00000000`0109ea70 00007ffc`722ca7d7 KERNELBASE!ReadConsoleInputA+0x14
00000000`0109eab0 00007ffc`7191a727 mscorwks!DoNDirectCall__PatchGetThreadCall+0x7b

00000000`0109ee30 00007ffc`721e0ec3 mscorwks!CallDescrWorker+0x82
00000000`0109ee80 00007ffc`726aa131 mscorwks!CallDescrWorkerWithHandler+0xd3
00000000`0109ef20 00007ffc`72239643 mscorwks!MethodDesc::CallDescr+0x2b1
00000000`0109f160 00007ffc`72103e84 mscorwks!ClassLoader::RunMain+0x22b
00000000`0109f3c0 00007ffc`7279693d mscorwks!Assembly::ExecuteMainMethod+0xbc
00000000`0109f6b0 00007ffc`720f7a03 mscorwks!SystemDomain::ExecuteMainMethod+0x47d
00000000`0109fc80 00007ffc`721143c4 mscorwks!ExecuteEXE+0x47
00000000`0109fcd0 00007ffc`729b7ced mscorwks!_CorExeMain+0xac
00000000`0109fd30 00007ffc`72a5ea5b mscoreei!_CorExeMain+0xe0
00000000`0109fd80 00007ffc`7be81611 MSCOREE!_CorExeMain_Exported+0xcb
00000000`0109fdb0 00007ffc`7dd164ad KERNEL32!BaseThreadInitThunk+0xd
00000000`0109fde0 00000000`00000000 ntdll!RtlUserThreadStart+0x1d

The highlighted frames are not properly resolved into symbolic information because they are relative to CLR2 assemblies (this can be inferred by the fact that the caller is code in mscorwks).

Once we reload the CLR2 DAC, the same command gives a different (better ) outcome:

0:000> kL
Child-SP          RetAddr           Call Site
00000000`0109e878 00007ffc`7b3d525e ntdll!ZwDeviceIoControlFile+0xa
00000000`0109e880 00007ffc`7b485400 KERNELBASE!ConsoleCallServerGeneric+0xe6
00000000`0109e9e0 00007ffc`7b49c318 KERNELBASE!GetConsoleInput+0x38820
00000000`0109ea70 00007ffc`722ca7d7 KERNELBASE!ReadConsoleInputA+0x14
00000000`0109eab0 00007ffc`7191a727 mscorwks!DoNDirectCall__PatchGetThreadCall+0x7b

00000000`0109ee30 00007ffc`721e0ec3 mscorwks!CallDescrWorker+0x82
00000000`0109ee80 00007ffc`726aa131 mscorwks!CallDescrWorkerWithHandler+0xd3
00000000`0109ef20 00007ffc`72239643 mscorwks!MethodDesc::CallDescr+0x2b1
00000000`0109f160 00007ffc`72103e84 mscorwks!ClassLoader::RunMain+0x22b
00000000`0109f3c0 00007ffc`7279693d mscorwks!Assembly::ExecuteMainMethod+0xbc
00000000`0109f6b0 00007ffc`720f7a03 mscorwks!SystemDomain::ExecuteMainMethod+0x47d
00000000`0109fc80 00007ffc`721143c4 mscorwks!ExecuteEXE+0x47
00000000`0109fcd0 00007ffc`729b7ced mscorwks!_CorExeMain+0xac
00000000`0109fd30 00007ffc`72a5ea5b mscoreei!_CorExeMain+0xe0
00000000`0109fd80 00007ffc`7be81611 MSCOREE!_CorExeMain_Exported+0xcb
00000000`0109fdb0 00007ffc`7dd164ad KERNEL32!BaseThreadInitThunk+0xd
00000000`0109fde0 00000000`00000000 ntdll!RtlUserThreadStart+0x1d

The same concept applies to references to managed objects on the stack, to the managed heap and to appdomains: commands like !dso, !dumpheap and !dumpdomain will only show managed references, managed heaps and appdomains of the CLR whose DAC dll is currently loaded in the debugger.

Exceptions

All managed exceptions are implemented in terms of SEH, and the SEH exception code for all clr exceptions is 0xe0434f4d, regardless the CLR version. This is good news, because this means that WinDbg knows about all the CLR exceptions, regardless which DAC dll (if any at all) is loaded.

The following command:

0:000> sxe clr

causes WInDbg to break the debugged process whenever a managed exception occurs.

Further investigation of the exception requires to load the right DAC dll. For instance:

0:000> g
(570.1d80): CLR exception - code e0434f4d (first chance)
First chance exceptions are reported before any exception handling.
This exception may be expected and handled.
KERNELBASE!RaiseException+0x68:
00007ffc`7b3d8384 488b8c24c0000000 mov     rcx,qword ptr [rsp+0C0h] ss:00000000`0109eac0=000058c9ee5dddb4

0:000> kbL
RetAddr           : Args to Child                                                           : Call Site
00007ffc`7220326f : 00000000`0118b750 00000000`0118b750 00000000`0109eb30 00000000`0118b750 : KERNELBASE!RaiseException+0x68
00007ffc`72711cf0 : 

 00000000`00000000 00000000`00000000 00000000`00000001 : mscorwks!RaiseTheExceptionInternalOnly+0x2ff
00007ffc`12a0020b : 00000000`70000001 00007ffc`128b33d8 00000000`00472054 00000000`011c8a20 : mscorwks!JIT_Throw+0x130
00007ffc`722cafb2 : 00000000`030dce80 00000000`00000000 00007ffc`128b39b8 00007ffc`721980f9 : 0x00007ffc`12a0020b
00007ffc`721e0ec3 : 00000000`00000002 00000000`0000000a 00007ffc`720874f0 00000000`00000000 : mscorwks!CallDescrWorker+0x82
00007ffc`726aa131 : 00000000`0109efb8 00000000`00000000 00000000`0109f1c0 00000000`00000008 : mscorwks!CallDescrWorkerWithHandler+0xd3
00007ffc`72239643 : 00000000`00000000 00000000`00000000 00000000`00000000 00000000`0109f420 : mscorwks!MethodDesc::CallDescr+0x2b1
00007ffc`72103e84 : 00000000`00000001 00000000`00000000 00000000`00000030 00000000`00000000 : mscorwks!ClassLoader::RunMain+0x22b
00007ffc`7279693d : 00000000`0109fa10 00000000`00000000 00000000`011a6f58 00000000`00000200 : mscorwks!Assembly::ExecuteMainMethod+0xbc
00007ffc`720f7a03 : 00000000`00000000 00000000`00000000 00000000`00000000 00007ffc`722623d2 : mscorwks!SystemDomain::ExecuteMainMethod+0x47d
00007ffc`721143c4 : ffffffff`fffffffe 00000000`00000000 000049e5`00000000 00000000`00000000 : mscorwks!ExecuteEXE+0x47
00007ffc`729b7ced : ffffffff`ffffffff 00000000`0118b750 00000000`00000000 00000000`0109fcd8 : mscorwks!_CorExeMain+0xac
00007ffc`72a5ea5b : 00000000`00000000 00007ffc`72114318 00000000`00000000 00000000`00000000 : mscoreei!_CorExeMain+0xe0
00007ffc`7be81611 : 00007ffc`729b0000 00000000`00000000 00000000`00000000 00000000`00000000 : MSCOREE!_CorExeMain_Exported+0xcb
00007ffc`7dd164ad : 00000000`00000000 00000000`00000000 00000000`00000000 00000000`00000000 : KERNEL32!BaseThreadInitThunk+0xd
00000000`00000000 : 00000000`00000000 00000000`00000000 00000000`00000000 00000000`00000000 : ntdll!RtlUserThreadStart+0x1d

0:000> !do 00000000`030e18a8
<Note: this object has an invalid CLASS field>
Invalid object

0:000> .cordll -I mscorwks -ve -u -l
Automatically loaded SOS Extension
CLRDLL: Loaded DLL C:\Windows\Microsoft.NET\Framework64\v2.0.50727\mscordacwks.dll
CLR DLL status: Loaded DLL C:\Windows\Microsoft.NET\Framework64\v2.0.50727\mscordacwks.dll

0:000> !do 00000000`030e18a8
Name: System.ApplicationException
MethodTable: 00007ffc7147c618
EEClass: 00007ffc710804c8
Size: 136(0x88) bytes
 (C:\WINDOWS\assembly\GAC_64\mscorlib\2.0.0.0__b77a5c561934e089\mscorlib.dll)
Fields:
              MT    Field   Offset                 Type VT     Attr            Value Name
00007ffc71477df0  40000b5        8        System.String  0 instance 0000000000000000 _className
00007ffc71476198  40000b6       10 ...ection.MethodBase  0 instance 0000000000000000 _exceptionMethod
00007ffc71477df0  40000b7       18        System.String  0 instance 0000000000000000 _exceptionMethodString
00007ffc71477df0  40000b8       20        System.String  0 instance 00000000030e1870 _message
00007ffc7146f410  40000b9       28 ...tions.IDictionary  0 instance 0000000000000000 _data
00007ffc714780b8  40000ba       30     System.Exception  0 instance 0000000000000000 _innerException
00007ffc71477df0  40000bb       38        System.String  0 instance 0000000000000000 _helpURL
00007ffc714776e0  40000bc       40        System.Object  0 instance 0000000000000000 _stackTrace
00007ffc71477df0  40000bd       48        System.String  0 instance 0000000000000000 _stackTraceString
00007ffc71477df0  40000be       50        System.String  0 instance 0000000000000000 _remoteStackTraceString
00007ffc7147f060  40000bf       70         System.Int32  1 instance                0 _remoteStackIndex
00007ffc714776e0  40000c0       58        System.Object  0 instance 0000000000000000 _dynamicMethods
00007ffc7147f060  40000c1       74         System.Int32  1 instance      -2146232832 _HResult
00007ffc71477df0  40000c2       60        System.String  0 instance 0000000000000000 _source
00007ffc7147a7f8  40000c3       68        System.IntPtr  1 instance                0 _xptrs
00007ffc7147f060  40000c4       78         System.Int32  1 instance       -532459699 _xcode

Summary

It is possible to debug multiple CLRs, but this can be done “one CLR at a time” in WinDbg + SOS. If you know about it and you switch among them, this can nonetheless provide for a good debugging experience. It’s important, however, to be aware that, at any given time during debugging, you have a partial view of what’s going on in the process, relative to one CLR only.

Visual Studio 2012 has the additional limitation of not allowing to switch the debugged CLR within the same debugging session.

Starting with version 4, the CLR supports In-Process Side-by-Side (InProc SxS).

The topic is extensively treated. In particular, this blog post does a very good job in explaining why CLR InProc Sxs is useful, and which scenarios it addresses.

However I could not find any sample code that causes multiple CLRs to be loaded into a process. I needed such a scenario in order to figure out how to do debugging with Windbg and Sos when multiple CLRs are loaded into a process.

So, the first step for me was to create a solution that causes multiple runtimes to be loaded into a process. The following step will then be to do managed debugging in such a process. This is the topic of a post to come, however . Let’s get started and create the solution then.

Note: there isn’t a 1:1 mapping between the .Net Framework version and the CLR version, because different versions of the .Net Framework may use the same version of the CLR. Also, the name of the CLR dll has changed over different versions. All this is summarized in the following table:

and will be useful in the rest of this post. Only the CLR version is relevant for our purposes, so the “Target Framework” in Visual Studio projects will be just a means to actually set the CLR version. In this respect, multiple options are possible: for instance, .Net Framework 2.0, .Net Framework 3.0 and .Net Framework 3.5 all set the CLR version to 2.0. In the samples, we’ll be using the last .Net Framework version that uses a given CLR version (.Net Framework 3.5 for CLR 2.0, .Net Framework 4.5 for CLR 4.0) at the time of this writing.

Easy approaches (and why they do not work)

Each assembly can reference one CLR, so obviously it’s not possible to load multiple CLRs in one process writing one assembly only,

It is tempting to think, however, that by having different assemblies in one process, each referencing a different version of the CLR, we end up loading multiple CLRs. Let’s try this way then.

CLR2 referencing CLR4

Follow these steps:

• Create a new solution of type “Blank Solution” in Visual Studio 2012
• Add a console application (ConsoleApplication1), with Target Framework version 3.5
• Add a class library (ClassLibrary1), with Target Framework version 4.5
• Add a reference to ClassLibrary1 from ConsoleApplication1
• Reference a type in ClassLibrary1 from ConsoleApplication1

Even before you build this solution, you’ll see this icon on the added reference:

Building gives an error that is pretty self-explanatory:

 1:  

 2:  

 3: 2>------ Build started: Project: ConsoleApplication1, Configuration: Debug Any CPU ------

 4: 2>C:\Windows\Microsoft.NET\Framework\v4.0.30319\Microsoft.Common.targets(1578,5): warning MSB3274: The primary reference "D:\CLR2CLR4\ClassLibrary1\bin\Debug\ClassLibrary1.dll" could not be resolved because it was built against the ".NETFramework,Version=v4.5" framework. This is a higher version than the currently targeted framework ".NETFramework,Version=v3.5".

 5: 2>C:\Windows\Microsoft.NET\Framework\v4.0.30319\Microsoft.Common.targets(1578,5): warning MSB3258: The primary reference "D:\CLR2CLR4\ClassLibrary1\bin\Debug\ClassLibrary1.dll" could not be resolved because it has an indirect dependency on the .NET Framework assembly "mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" which has a higher version "4.0.0.0" than the version "2.0.0.0" in the current target framework.

 6: 2>D:\SR\CLR2CLR4\ConsoleApplication1\Program.cs(5,7,5,20): error CS0246: The type or namespace name 'ClassLibrary1' could not be found (are you missing a using directive or an assembly reference?)

At startup, CLR2 would be loaded, and the reference to an assembly targeting the CLR4 would force that assembly to be run in a previous version of the CLR. This is not supported.

CLR4 referencing CLR2

Follow these steps (you can reuse the previous solution)

• Add a console application (ConsoleApplication2), with Target Framework version 4.5
• Add a class library (ClassLibrary2), with Target Framework version 3.5
• Add a reference to ClassLibrary2 from ConsoleApplication2
• Reference a type in ClassLibrary2 from ConsoleApplication2. Note that this time the reference is added without any warning

If you run the solution, everything works fine. A closer inspection, however, shows that only CLR4 is loaded into the process (you can attach a debugger to the process, or use Sysinternals’ Process Explroer, and check that clr.dll is loaded into the process, but mscorwks.dll is not).

These two tests have one thing in common: directly referencing types between different versions of the CLR does not cause multiple CLRs to be loaded. This is logical, because a direct reference between types implies that they live in the same AppDomain. Having different CLRs loaded, however, means that these CLRs live side-by-side in the same process, separate from each other. This means that every CLR has its own Garbage Collector, JIT Compiler, set of AppDomains, and in general all the supporting structures are separate. The obvious consequence is that two .Net objects referencing each other cannot live in different CLRs. 

A more serious approach (and why it still does not work)

This excellent post has valuable information on how multiple CLRs can be loaded into a process (see the section “Our Solution Is Not…”):

To take advantage of in-proc SxS, a managed component must be activated by a native host and interact with its environment through a native interop layer such as COM interop and P/Invoke.

So we come up with the idea of a managed application targeting a version of the CLR, and a managed assembly, exposed through COM Interoperability, targeting a different version of the CLR. Follow these steps (you can reuse the previous solution):

• Add a console application (ConsoleApplication3), with Target Framework version 3.5
• Add a class library (ClassLibrary3), with Target Framework version 4.5
• In ClassLibrary3, expose a .Net class through COM Interop. This requires using the ComVisible attribute and registering the assembly with COM through RegAsm.
• Build ClassLibrary3. Upon successful build, the regasm step creates the Type Library for use with COM Interop
• Add a COM Reference in ConsoleApplication3 to the Type Library generated by building ClassLibrary3

The last step fails and displays a message box with this content:

 1: ---------------------------

 2: Microsoft Visual Studio

 3: ---------------------------

 4: A reference to 'ClassLibrary3' could not be added. 

 5:  

 6: The ActiveX type library 'D:\CLR2CLR4\ClassLibrary3\bin\Debug\bin\Debug\ClassLibrary3.tlb' was exported from a .NET assembly and cannot be added as a reference.

 7:  

 8: Add a reference to the .NET assembly instead.

 9: ---------------------------

 10: OK   

 11: ---------------------------

Basically, this means that it is not possible to use managed code from managed code through COM Interop.

The final solution

Due to the previous limitation, we have to introduce a native intermediary in the chain of calls.

Follow these steps (you can reuse the previous solution):

• Add an ATL Project (ATLProject1) to the solution
• Add an ATL Simple Object to ATLProject1. This object just forwards calls to the object in ClassLibrary3 exposed through COM Interop
• Build ATLProject1
• Add a COM Reference in ConsoleApplication3 to the Type Library generated by building ATLProject1

Build and run the solution (startup project: ConsoleApplication3). Everything works fine and, if you look at the dlls loaded into the process (again, you can either attach a debugger or use Project Explorer), you’ll see that both mscorwks.dll (CLR2) and clr.dll (CLR4) are loaded into the project.

The final Visual Studio 2012 solution, including 7 projects, is attached to this post. Note that only 3 projects (ConsoleApplication3, ClassLibrary3 and ATLProject1) are needed to have multiple CLRs loaded in a process. The other projects (ConsoleApplication1, ClassLibrary1, ConsoleApplication2, ClassLibrary2) exemplify the non-working approaches.

Note: You would get the same effect (CLR2 and CLR4 loaded) by reversing the CLR versions in the projects. In other words, if ConsoleApplication3 had Target Framework version 4.5, and ClassLibrary3 had Target Framework version 3.5, the end result would still be to have CLR2 and CLR4 loaded in the process, only in the reverse order (CLR4 first, then CLR2).

In the next post, we’ll use this solution to show how managed debugging works with CLR InProc SxS. Stay tuned!

CLR2CLR4.zip

I got an interesting question from a customer a few days ago: “Is it possible to handle cancellation in a CodeActivity?”

The background for this question is the following: an activity can explicitly handle cancellation by overriding its Cancel() method. However, out of the 4 activity authoring options (Activity, CodeActivity, AsyncCodeActivity and NativeActivity), only AsyncCodeActivity and NativeActivity have the Cancel() virtual method.

Turns out that, in order to properly address the question, a bit of background information is needed. This is what this post is all about. A deep understanding of how cancellation works is useful when writing custom activities. I have seen more than one situation when “unexpected” workflow behavior was due to poor implementation of cancellation for one of its activities.

The post also provides a pattern for proper implementation of cancellation using the declarative (Activity) authoring option.

How cancellation works

Cancellation is a request from the parent for graceful, early termination of a child activity. A parent does this by calling NativeActivityContext.CancelChildren() or NativeActivityContext.CancelChild(ActivityInstance).

Note: this same functionality is available to the host through WorkflowApplication.Cancel() and WorkflowInvoker.CancelAsync(): they request cancellation of the root ActivityInstance.

The workflow runtime does the following when CancelChild()/CancelChildren() are called (you can look at this logic with a .NET Reflection Tool like .Net Reflector or ILSpy, the actual logic is in ActivityExecutor.CancelActivity()):

1. If the child ActivityInstance is in a completed state (Closed, Canceled or Faulted), nothing happens
2. If the child ActivityInstance is in the Executing state
1. if it does not have pending work (children in the Executing state, outstanding bookmarks or pending asynchronous operations), the ActivityInstance is transitioned to the Canceled state without executing any work item of that ActivityInstance.
2. otherwise, a CancelActivityWorkItem for the child ActivityInstance is scheduled for execution.

The important thing to note is that only in 2.b above the cancellation of an ActivityInstance implies the execution of a work item on the ActivityInstance itself. In cases 1 and 2.a the cancellation does not involve calling any methods on the activity.

Also note that 2.a above can only hold if the child ActivityInstance has been scheduled, but hasn’t executed any work item yet. This is because, as part of the post-processing of work item execution, the WF Runtime transitions the ActivityInstance to a completed state if the ActivityInstance has no pending work. This logic is in ActivityInstance.UpdateState().

Everything else about cancellation stems from the simple rules above, and from the fundamental rule of the WF Runtime: work items for a given WorkflowInstance are executed sequentially.

What happens next?

As a former colleague of mine used to say: “When I don’t know, I go and look” :-). Again, a .NET Reflection Tool is our friend here.

The actual function that is called by the execution of CancelActivityWorkItem is InternalCancel():

internal class CancelActivityWorkItem : ActivityExecutionWorkItem 
{
    ...
    public override bool Execute(ActivityExecutor executor, BookmarkManager bookmarkManager) 
    { 
        try 
        { 
            ActivityInstance.Cancel(executor, bookmarkManager); 
        } 
        catch (Exception exception) 
        { 
            if (Fx.IsFatal(exception)) 
                throw; 
            ExceptionToPropagate = exception; 
        } 
        return true; 
    }
}

public sealed class ActivityInstance : ActivityInstanceMap.IActivityReferenceWithEnvironment, ActivityInstanceMap.IActivityReference 
{ 
    ...
    internal void Cancel(ActivityExecutor executor, BookmarkManager bookmarkManager) 
    { 
        Activity.InternalCancel(this, executor, bookmarkManager); 
    } 
 } 

So how cancellation works for the 4 different activity authoring options actually boils down to how each of them implements the virtual method InternalCancel(). Let’s look at each case.

Activity

public abstract class Activity
 { 
    ... 
    internal virtual void InternalCancel(ActivityInstance instance, ActivityExecutor executor, BookmarkManager bookmarkManager) 
    { 
        NativeActivityContext item = executor.NativeActivityContextPool.Acquire(); 
        try 
        { 
            item.Initialize(instance, executor, bookmarkManager); 
            item.Cancel(); 
        } 
        finally 
        { 
            item.Dispose(); 
            executor.NativeActivityContextPool.Release(item); 
        } 
    } 
 }

public class NativeActivityContext : ActivityContext 
{ 
    ... 
    internal void Cancel() 
    { 
        ThrowIfDisposed(); 
        CurrentInstance.BaseCancel(this); 
    } 
 }

public sealed class ActivityInstance : ActivityInstanceMap.IActivityReferenceWithEnvironment, ActivityInstanceMap.IActivityReference 
{ 
    ... 
    internal void BaseCancel(NativeActivityContext context) 
    { 
        performingDefaultCancelation = true; 
        CancelChildren(context); 
    } 
 }

CodeActivity

public abstract class CodeActivity : Activity 
{ 
    ... 
    internal sealed override void InternalCancel(ActivityInstance instance, ActivityExecutor executor, BookmarkManager bookmarkManager) 
    { 
    } 
}

AsyncCodeActivity

public abstract class AsyncCodeActivity : Activity, IAsyncCodeActivity 
{ 
    ...
    protected virtual void Cancel(AsyncCodeActivityContext context) 
    { 
    } 

    internal sealed override void InternalCancel(ActivityInstance instance, ActivityExecutor executor, BookmarkManager bookmarkManager) 
    { 
        AsyncOperationContext context; 
        if (executor.TryGetPendingOperation(instance, out context)) 
        { 
            using (AsyncCodeActivityContext context2 = new AsyncCodeActivityContext(context, instance, executor)) 
            { 
                context.HasCalledAsyncCodeActivityCancel = true; 
                Cancel(context2); 
            } 
        } 
    } 
 }

This means that by default cancellation on an AsyncCodeActivity is a no-op, but the activity author has a chance to implement its own cancel semantics. According to the rules above, Cancel() for an AsyncCodeActivity will be called only if BeginExecute() has already been executed, and EndExecute() has not: in this time interval, there is a pending async operation for the activity. A typical implementation of Cancel() will consist in canceling the asynchronous operation that was issued in BeginExecute(), if it hasn’t completed yet. The WF runtime has no knowledge of this asynchronous operation and how to cancel it, so it cannot implement a meaningful cancellation logic. Therefore, it gives the activity author the option to do it.

NativeActivity

public abstract class NativeActivity : Activity, IInstanceUpdatable 
 { 
    ... 
    protected virtual void Cancel(NativeActivityContext context) 
    { 
        if (!context.IsCancellationRequested) 
            throw FxTrace.Exception.AsError(new InvalidOperationException(SR.DefaultCancelationRequiresCancelHasBeenRequested)); 
        context.Cancel(); 
    } 

    internal override void InternalCancel(ActivityInstance instance, ActivityExecutor executor, BookmarkManager bookmarkManager) 
    { 
        NativeActivityContext context = executor.NativeActivityContextPool.Acquire(); 
        try 
        { 
            context.Initialize(instance, executor, bookmarkManager); 
            Cancel(context); 
        } 
        finally 
        { 
            context.Dispose(); 
            executor.NativeActivityContextPool.Release(context); 
        } 
    } 
 }

The implementation is somewhat similar to that of AsyncCodeActivity, but here Cancel() calls context.Cancel(). Context.Cancel(), as we have seen in the section on Activity above, propagates the cancellation request to children. This is necessary for NativeActivity and not for AsyncCodeActivity, because NativeActivity, unlike AsyncCodeActivity, can have children.

Summary of Cancellation Behavior

We can summarize the considerations above with a simple table:

Custom Cancellation

If the default implementation of cancellation for AsyncCodeActivity and NativeActivity does not suit your needs, you can override it. Overriding NativeActivity.Cancel() is called custom cancellation, as opposed to the behavior provided by NativeActivity.Cancel(), which is called default cancellation. Here I am providing some quick considerations on custom cancellation.

Cancellation of Children

NativeActivity.Cancel(), as mentioned above, propagates the cancelation request to all the child ActivityInstances. If you override Cancel(), however, it is your responsibility to propagate cancellation requests to children, if applicable. You can do this selectively, by calling Context.CancelChild(ActivityInstance inst), or in a generalized fashion, by calling Context.CancelChildren(). Cancel() is free not to do cancellation of children, however this prevents the activity itself from transitioning to a completed state. So, in essence, such an implementation of Cancel() would not allow an early completion of the activity.

Scheduling of Children

You may have noted that, whenever default cancellation is carried out, as opposed to custom cancellation, the performingDefaultCancelation field of ActivityInstance is set to true (see the code snippet for ActivityInstance.BaseCancel() above). This setting is used because default cancellation prevents scheduling of new child activities. Or, better: scheduling an activity for execution when default cancellation is in progress causes NativeActivityContext.ScheduleActivity() to return an ActivityInstance whose state is Canceled. This logic is implemented in NativeActivityContext.InternalScheduleActivity(), called by NativeActivityContext.ScheduleActivity():

private ActivityInstance InternalScheduleActivity(Activity activity, CompletionBookmark onCompleted, FaultBookmark onFaulted)
{
    ...
    if (currentInstance.IsPerformingDefaultCancelation)
    {
        currentInstance.MarkCanceled();
        return ActivityInstance.CreateCanceledInstance(activity);
    }
    return executor.ScheduleActivity(activity, currentInstance, onCompleted, onFaulted, null);
}

Overriding Cancel() disables this behavior, so you’ll be able to continue scheduling child activities for execution. This is, indeed, one reason why you may want to implement custom cancellation: as part of your cancellation logic, your activity may need to execute child activities. Some OOB activities do exactly that. For instance, the CancellationScope activity schedules the CancellationHandler child activity when its child Body is cancelled. However, if Body were cancelled as the result of default cancellation of its parent, CancellationScope would not be able to schedule CancellationHandler at that point. Therefore, CancellationScope overrides Cancel(). The CompensableActivity OOB activity also uses this technique. Keep in mind that, if your override of Cancel() calls base.Cancel(), default cancellation kicks in and scheduling of children would again be disallowed. For this reason, base.Cancel() should not be called by an override of Cancel(), if the cancellation logic requires execution of child activities.

Bookmarks

Other than having running children, the other reason why a NativeActivity may stay in the Executing state is outstanding bookmarks. If your activity is in the Executing state and has outstanding bookmarks when cancellation is requested, Cancel() will be called, per rule 2.b above.

What happens next depends on whether default cancellation or custom cancellation is being used. Let’s experiment with this ourselves. Run the following code:

class Program
{
    static void Main(string[] args)
    {
        ManualResetEvent mre = new ManualResetEvent(false);
        Activity workflow1 = new MyActivity();
        WorkflowApplication wfApp = new WorkflowApplication(workflow1);
        wfApp.Completed = wacea => { Console.WriteLine("Workflow Completed"); mre.Set(); };
        wfApp.Run();
        // give root activity a chance to execute its first work item
        Thread.Sleep(1000);
        wfApp.Cancel(TimeSpan.MaxValue);
        mre.WaitOne();
    }
}
public class MyActivity : NativeActivity
{
    Variable<Bookmark> m_Bookmark;

    public MyActivity()
    {
        m_Bookmark = new Variable<Bookmark>();
    }

    protected override bool CanInduceIdle
    {
        get
        {
            return true;
        }
    }

    protected override void CacheMetadata(NativeActivityMetadata metadata)
    {
        metadata.AddImplementationVariable(m_Bookmark);
    }
        
    protected override void Execute(NativeActivityContext context)
    {
        Console.WriteLine("Execute called");
        Bookmark bmk = context.CreateBookmark();
        context.SetValue(m_Bookmark, bmk);
    }

    protected override void Cancel(NativeActivityContext context)
    {
        Console.WriteLine("Cancel called");
        base.Cancel(context);
    }
}

internal abstract class ActivityExecutionWorkItem : WorkItem
{
    ...
    public override void PostProcess(ActivityExecutor executor)
    {
        if ((ExceptionToPropagate != null) && !skipActivityInstanceAbort)
            executor.AbortActivityInstance(ActivityInstance, ExceptionToPropagate);
        else if (ActivityInstance.UpdateState(executor))
        {
            Exception exception = executor.CompleteActivityInstance(ActivityInstance);
            if (exception != null)
                ExceptionToPropagate = exception;
        }
    }
}

public sealed class ActivityInstance : ActivityInstanceMap.IActivityReferenceWithEnvironment, ActivityInstanceMap.IActivityReference
{
    ...
    internal bool UpdateState(ActivityExecutor executor)
    {
        ...
        if (performingDefaultCancelation && OnlyHasOutstandingBookmarks)
        {
            RemoveAllBookmarks(executor.RawBookmarkScopeManager, executor.RawBookmarkManager);
            MarkCanceled();
            SetCanceled();
            flag = true;
        }
        return flag;
    }
}

• default cancellation is used (performingDefaultCancellation is true)
• pending work ONLY consists of outstanding bookmarks

Let’s remove one of these conditions by modifying Cancel(), so that the base Cancel() is not called:

protected override void Cancel(NativeActivityContext context)
{
    Console.WriteLine("Cancel called");
}

The bottom line, in any case, is that you don’t need to care about outstanding bookmarks, as long as you rely on default cancellation. If you are using custom cancellation, however, it is your responsibility to remove outstanding bookmarks, otherwise your ActivityInstance, and hence the workflow, will not complete. However, if your activity has custom cancellation, and it has executing children AND outstanding bookmarks, it is not necessarily a good idea to remove all bookmarks in the Cancel() override, because child activities that are still executing may use those bookmarks. If this is the case, a good strategy would be to remove all bookmarks once all children have completed. The parent activity can detect when all children have completed by always scheduling a completion callback every time a child activity is scheduled for execution.

As a side note: the components that resume bookmarks for the activity (typically the host, through WorkflowApplication.ResumeBookmark(), or other activities, through NativeActivityContext.ResumeBookmark()) should be resilient to the possibility that the bookmark is no longer there, because the ActivityInstance owning the bookmark has been canceled in the meantime. The different overrides of ResumeBookmark() return a BookmarkResumptionResult value that tells the caller if the bookmark is no longer present (BookmarkResumptionResult.NotFound).

Handling the Completion States Canceled and Closed

The fact that cancellation has been requested for an ActivityInstance does not imply that the ActivityInstance will complete its execution in the ActivityInstanceState.Canceled state. Let’s review the cancellation rules defined above:

• if 1. holds: no change is made to the completed state (which will typically be Closed)
• if 2.a holds: the completed state will always be Canceled
• if 2.b holds: the logic is more complex, as we are going to find out now.

If 2.b holds, ActivityInstance will transition to the Canceled state if ActivityInstance.MarkCanceled() is called. MarkCanceled() is simple:

public sealed class ActivityInstance : ActivityInstanceMap.IActivityReferenceWithEnvironment, ActivityInstanceMap.IActivityReference
{
    ...
    internal void MarkCanceled()
    {
        substate = Substate.Canceling;
    }
}

public sealed class ActivityInstance : ActivityInstanceMap.IActivityReferenceWithEnvironment, ActivityInstanceMap.IActivityReference
{
    ...
    internal bool UpdateState(ActivityExecutor executor)
    {
        ...
        if (!HasPendingWork)
        {
            if (!executor.IsCompletingTransaction(this))
            {
                flag = true;
                if (substate == Substate.Canceling)
                {
                    SetCanceled();
                    return flag;
                }
                SetClosed();
            }
            return flag;
        }
        ...
    }

internal class ActivityExecutor : IEnlistmentNotification
{
    ...
    public void CancelActivity(ActivityInstance activityInstance)
    {
        if ((activityInstance.State == ActivityInstanceState.Executing) && !activityInstance.IsCancellationRequested)
        {
            activityInstance.IsCancellationRequested = true;
            if (activityInstance.HasNotExecuted)
                scheduler.PushWork(CreateEmptyWorkItem(activityInstance));
            else
                scheduler.PushWork(new CancelActivityWorkItem(activityInstance));
            if (ShouldTrackCancelRequestedRecords)
                AddTrackingRecord(new CancelRequestedRecord(WorkflowInstanceId, activityInstance.Parent, activityInstance));
        }
    }
}

public sealed class ActivityInstance : ActivityInstanceMap.IActivityReferenceWithEnvironment, ActivityInstanceMap.IActivityReference
{
    ...
    internal bool UpdateState(ActivityExecutor executor)
    {
        bool flag = false;
        if (HasNotExecuted)
        {
            if (this.IsCancellationRequested)
            {
                if (this.HasChildren)
                    foreach (ActivityInstance instance in this.GetChildren())
                        executor.CancelActivity(instance);
                return flag;
            }
            SetCanceled();
            return true;
        }
    }
    ...
}

public sealed class ActivityInstance : ActivityInstanceMap.IActivityReferenceWithEnvironment, ActivityInstanceMap.IActivityReference
{
    ...
    private void SetClosed()
    {
        state = ActivityInstanceState.Closed;
    }

    private void SetCanceled()
    {
        TryCancelParent();
        state = ActivityInstanceState.Canceled;
    }

    private void TryCancelParent()
    {
        if ((parent != null) && parent.IsPerformingDefaultCancelation)
            parent.MarkCanceled();
    }
}

class Program
{
    static void Main(string[] args)
    {
        ManualResetEvent mre = new ManualResetEvent(false);
        Activity workflow1 = new MyActivity();
        WorkflowApplication wfApp = new WorkflowApplication(workflow1);
        wfApp.Completed = wacea => { Console.WriteLine("Workflow Completed with status " + wacea.CompletionState); mre.Set(); };
        wfApp.Run();
        // give root activity a chance to execute its first work item
        Thread.Sleep(1000);
        wfApp.Cancel(TimeSpan.MaxValue);
        mre.WaitOne();
    }
}

public class MyActivity : NativeActivity
{
    private Delay myDelayChild;

    public MyActivity()
    {
        myDelayChild = new Delay
        {
            Duration = new InArgument<TimeSpan>(TimeSpan.FromSeconds(10))
        };
    }

    protected override void CacheMetadata(NativeActivityMetadata metadata)
    {
        metadata.AddImplementationChild(myDelayChild);
    }

    protected override void Execute(NativeActivityContext context)
    {
        context.ScheduleActivity(myDelayChild);
    }
}

protected override void Cancel(NativeActivityContext context)
{
    context.CancelChildren();
}

protected override void Execute(NativeActivityContext context)
{
    context.ScheduleActivity(myDelayChild, onDelayChildCompleted);
}

private void onDelayChildCompleted(NativeActivityContext context, ActivityInstance completedInstance)
{
    if (completedInstance.State == ActivityInstanceState.Canceled)
        context.MarkCanceled();
}

private void OnConditionComplete(NativeActivityContext context, ActivityInstance completedInstance, bool result)
{
    if (result)
    {
        context.CancelChildren();
        hasCompleted.Set(context, true);
    }
}

private void OnBranchComplete(NativeActivityContext context, ActivityInstance completedInstance)
{
    if ((CompletionCondition != null) && !hasCompleted.Get(context))
    {
        if ((completedInstance.State != ActivityInstanceState.Closed) && context.IsCancellationRequested)
        {
            context.MarkCanceled();
            hasCompleted.Set(context, true);
        }
        else
        {
            if (onConditionComplete == null)
                onConditionComplete = new CompletionCallback<bool>(OnConditionComplete);
            context.ScheduleActivity<bool>(CompletionCondition, onConditionComplete, null);
        }
    }
}

Custom Cancellation Summary

If you are implementing custom cancellation, there are 3 quick takeaways:

• It is your responsibility to propagate the cancellation request to running children
• It is your responsibility to remove outstanding bookmarks
• It is your responsibility to correctly set the completion state of the ActivityInstance: Closed if the ActivityInstance successfully completed its work after receiving a cancel request, Canceled otherwise.

Cancellation with the Activity authoring option: CancellationScope

• Do some work (possibly split into several parts)
• If an external condition holds that prevents the work from completing, send a notification about unsuccessful completion

Using the declarative authoring option, you may create a sequence of 2 other activities:

Sequence
    GatherSomeData
    ProcessTheData

If cancellation arrives from the host while either GatherSomeData or ProcessTheData are executing, the activities complete in the Canceled state, which causes Sequence to be canceled as well. Otherwise, if both GatherSomeData and ProcessTheData complete in the Closed state, Sequence also completes in the Closed state.

This gives way for wrapping Sequence in a CancellationScope activity:

CancellationScope
    Body = Sequence
        GatherSomeData
        ProcessTheData
    CancellationHandler = SendCandelDataProcessingEmail

public sealed class CancellationScope : NativeActivity
{
    ...
    protected override void Cancel(NativeActivityContext context)
    {
        if (!suppressCancel.Get(context))
            context.CancelChildren();
    }

    private void OnBodyComplete(NativeActivityContext context, ActivityInstance completedInstance)
    {
        if ((completedInstance.State == ActivityInstanceState.Canceled) || 
               (context.IsCancellationRequested && (completedInstance.State == ActivityInstanceState.Faulted)))
        {
            suppressCancel.Set(context, true);
            context.MarkCanceled();
            if (CancellationHandler != null)
                context.ScheduleActivity(CancellationHandler, new FaultCallback(OnExceptionFromCancelHandler));
        }
    }
}

These scripts are all related to Workflow Foundation, and in this post I try to clarify what each script is used for.

Scripts usually come in pair, with a XxxSchema.sql file matched by a XxxLogic.sql file. The XxxSchema.sql file creates tables and views, the XxxLogic.sql file creates stored procedures, functions, triggers etc. The pairs are always meant to be executed in this order: XxxSchema.sql first, then XxxLogic.sql. Scripts in a pair should be run in the same database.

SqlPersistenceService_Schema.sql and SqlPersistenceService_Logic.sql

These scripts are used for WF3 persistence. You may wonder why these scripts, that refer to WF3, are in the folder of the .Net Framework 4.x. This is because WF3 is also in .Net 4.x, as I pointed out in my previous post. If you are using WF3 in .Net 4, use these scripts to create the workflow persistence DB.

The DB schema for WF3 is relatively simple, with only 2 tables: dbo.InstanceState and dbo.CompletedScope. dbo.InstanceState hosts the actual persisted workflow instances, dbo.CompletedScope is used only in advanced scenarios (compensation).

Tracking_Schema.sql and Tracking_Logic.sql

WF3 ships with a tracking service, System.Workflow.Runtime.Tracking.SqlTrackingService, that writes information to a Sql Server database. You create such a database by running Tracking_Schema.sql and Tracking_Logic.sql. You need the tracking database only if you are using SqlTrackingService. It is possible, though not mandatory, to use the same database for persistence and tracking. In other words, you can run SqlPersistenceService_Schema.sql SqlPersistenceService_Logic.sql, Tracking_Schema.sql and Tracking_Logic.sql in the same database.

WF4 has a different tracking architecture. Also, it ships a tracking participant, EtwTrackingParticipant, that tracks information to .etl files, not to Sql Server. Consequently, there is no equivalent of Tracking_Schema.sql and Tracking_Logic.sql in WF4.

SqlPersistenceProviderSchema.sql and SqlPersistenceProviderLogic.sql

WF in the .Net Framework 3.5 (WF3.5) adds support for Workflow Durable Services, and this requires an update to both the schema and the logic of the database. SqlPersistenceProviderSchema.sql and SqlPersistenceProviderLogic.sql update the persistence database accordingly. Note that these scripts should be executed in an existing WF3 persistence database, that is a database where SqlPersistenceService_Schema.sql and SqlPersistenceService_Logic.sql have already been run.

SqlPersistenceProviderSchema.sql adds the dbo.InstanceData table. SqlPersistenceProviderLogic.sql adds the dbo.DeleteInstance, dbo.InsertInstance, dbo.LoadInstance, dbo.UnlockInstance and dbo.UpdateInstance stored procedures.

SqlWorkflowInstanceStoreSchema.sql and SqlWorkflowInstanceStoreLogic.sql

WF4 introduces a completely new object model, and with it comes a different schema of the persistence database. SqlWorkflowInstanceStoreSchema.sql and SqlWorkflowInstanceStoreLogic.sql create a database suitable for persisting WF4 workflows. The script files are named after the class in WF4 that implements workflow persistence in SqlServer:,System.Activities.DurableInstancing.SqlWorkflowInstanceStore, The structure of the WF4 persistence database is more complex than the structure of the WF3 database. SqlWorkflowInstanceStoreSchema.sql creates a number of tables and views:

SqlWorkflowInstanceStoreLogic.sql adds stored procedures and functions:

SqlWorkflowInstanceStoreSchemaUpgrade.sql

WF4.5 introduces versioning. SqlWorkflowInstanceStoreSchemaUpgrade.sql updates the database created by SqlWorkflowInstanceStoreSchema.sql and SqlWorkflowInstanceStoreLogic.sql to accommodate for versioning information. The step-by-step procedure is documented here.

Note that you can save and reload WF4.5 workflows in WF4 databases (that is, databases created with SqlWorkflowInstanceStoreSchema.sql and SqlWorkflowInstanceStoreLogic.sql, but without SqlWorkflowInstanceStoreSchemaUpgrade.sql), as long as you do not associate versioning information to them.

The upgrade of the database consists of these main steps:

• New tables are created to handle versioning: DefinitionIdentityTable and IdentityOwnerTable
• Existing tables are altered with additional columns: InstancesTable.SurrogateIdentityId, RunnableInstancesTable.SurrogateIdentityId, LockOwnersTable.WorkflowIdentityFilter,
• Values are inserted in new tables and in new columns of existing tables, to represent standard versioning information for the workflow instances persisted in the database
• New views and stored procedures are created.

After executing the script, you’ll see the new tables:

The set of stored procedures and functions is the same of the WF4 version.

DropXxx.sql

The DropXxx.sql scripts drop tables and other artifacts. They are useful when a database hosts something else, in addition to persistence or tracking information. In that case, deleting the entire database would cause loss of data.

The versions of SqlWorkflowInstanceStoreXxx.sql

There is one further consideration that applies to SqlWorkflowInstanceStoreSchema.sql and SqlWorkflowInstanceStoreLogic.sql: if you compare these scripts on a machine with the .Net Framework 4.0, and on a machine with the .Net Framework 4.5 installed, you’ll find that they are different. This is because the .Net Framework 4.5 ships with versions of these files that directly create a WF4.5 database. For instance, SqlWorkflowInstanceStoreSchema.sql in the 4.5 version of the .Net Framework creates the  DefinitionIdentityTable, whereas the SqlWorkflowInstanceStoreSchema.sql in the 4.0 version of the .Net Framework does not.

Why is that? Well, if you installed the 4.5 version of the framework and subsequently create a WF Persistence Database, it makes sense to create it with a structure that is suitable for WF4.5 workflows. Note that SqlWorkflowInstanceStoreSchemaUpgrade.sql still has its own place: if you have an existing WF4 persistence database, you should run SqlWorkflowInstanceStoreSchemaUpgrade.sql against it, instead of running the 4.5 version of SqlWorkflowInstanceStoreSchema.sql and SqlWorkflowInstanceStoreLogic.sql: this way, you would preserve the workflow instances currently persisted in the database.

Which scripts to use?

Here is a quick summary of which scripts you need, depending on the version of WF that you are using:

   

	WF3	WF3.5	WF4	WF4.5
SqlPersistenceService_Schema.sql SqlPersistenceService_Logic.sql	X	X
SqlPersistenceProviderSchema.sql SqlPersistenceProviderLogic.sql		X
Tracking_Schema.sql Tracking_Logic.sql	X	X
SqlWorkflowInstanceStoreSchema.sql SqlWorkflowInstanceStoreLogic.sql			X	X
SqlWorkflowInstanceStoreSchemaUpgrade.sql				X

Scripts that are used by WF3 are also found in previous versions of the framework. So it should not come as a surprise to you that, under the folder %systemroot%\Microsoft.NET\Framework\v3.0\Windows Workflow Foundation\SQL\en, you find 4 script files: SqlPersistenceService_Schema.sql, SqlPersistenceService_Logic.sql, Tracking_Schema.sql and Tracking_Logic.sql. Likewise, you’ll find SqlPersistenceProviderSchema.sql and SqlPersistenceProviderLogic.sql in the %systemroot%\Microsoft.NET\Framework\v3.5\SQL\EN folder. And. since WF3 that ships with the .Net Framework 4.x is the same that ships with .Net Framework 3.x, the script files with the same name on different folders are identical, save for references to assemblies: Tracking_Schema.sql in %systemroot%\Microsoft.NET\Framework\v3.0\Windows Workflow Foundation\SQL\en references mscorlib version 2.0.0.0 and System.Workflow.ComponentModel version 3.0.0.0, whereas Tracking_Schema.sql in %systemroot%\Microsoft.NET\Framework64\v4.0.30319\SQL\en references mscorlib version 4.0.0.0 and System.Workflow.ComponentModel version 4.0.0.0.

The Problem

Assume you have a COM interface of your own, defined in an .IDL file, which accepts method arguments of type IXMLDOMXxx. For example, let’s say your interface has a method that looks like this:

[id(1), helpstring("method Load")] HRESULT Load([in] IXMLDOMNode* pXDN);

For your IDL to be compiled successfully by the MIDL compiler, the reference to IXMLDOMNode needs to be resolved. This happens automatically if you use the default import statements that are generated for a new IDL file in Visual Studio:

So your .IDL file compiles successfully and everything seems to be OK.

Now let’s use OLEVIEW, a utility program that ships with Visual Studio and the Platform SDK, to look at the generated type library (.TLB file). If you open the type library, you’ll see that IXMLDOMNode, along with many other IXMLDOMXxx interfaces, are included in the generated .TLB file:

This problem is more common than one may initially think, as shown by the many posts like this one out on the net:

http://www.eggheadcafe.com/software/aspnet/30162765/msxml-interfaces-appearin.aspx

We will be using Visual Studio 2008 and the Platform SDK version 6.0A. I would expect, but I cannot guarantee, that the following analysis is not version-dependent.

Type Library Registration

You may wonder at this stage: why is it so relevant to reference IXMLDOMNode from the generated TLB, instead of embedding it?

The main reason is that, when the TLB is registered, the interface-related registry keys under HKCR\Interface are changed, so as to associate IXMLDOMNode with your own type library.

Note

As an aside, note that the registration of a type library can happen in different ways. The API RegisterTypeLib does the registration, but most often a type library is registered as part of a COM dll registration through regsvr32.exe, or by calling its DllRegisterServer exported function. Yet another way to register a type library is by calling regsvcs or regasm on a .NET Assembly which has COMVisible types. In all these cases, the type library can be in a .TLB file or embedded as a resource in a .DLL.

Back to the point: the registration of the type library modifies keys under HKCR\Interface, we said. In the case above, if we look at the registry key {2933BF80-7B36-11d2-B20E-00C04F983E60}, the Interface ID (IID) of IXMLDOMNode, before we register our type library:

and after:

we understand what the difference is. Note that F31AF329-0FE0-4640-80F8-40D187FF4D8B is the Library ID (LibID) of the generated type library.

The fact that now the XML interfaces are associated with your type library instead of the standard type library included in msxml6.dll is not going to create trouble, initially. What happens, however, if you remove your type library, typically as part of uninstalling a program? The reference, in the registry, to your type library won’t be resolved and runtime errors will occur.

Changes in Vista and later OSes

Actually, when speaking about registering a type library, the outcome is different depending on the operating system and the way registration occurs. Let’s go deep into this as it provides an interesting view on some nifty details.

In operating systems up to, and including, Windows 2003, the registry key HKCR\Interface has the permission “Full Control” for the Administrators group:

Also, the “Full Control” permission is inherited by subkeys, so any user in the local Administrators group can do the registration and successfully update the keys.

From Vista, Administrators have “Read” permission on the registry keys representing LibIDs, and only TrustedInstaller has “Full Control” permission by default:

This means that, even if you are doing the registration with elevated privileges, or with UAC disabled, those registry keys cannot be changed – only setup programs, by having the TrustedInstaller credentials, will be able to do the registration.

So what happens if you do the registration through RegisterTypeLib, or by running regsvr32.exe from the command prompt, or if you call DllRegisterServer directly, in Vista and later OSes? Turns out the outcome is fairly interesting.

• RegisterTypeLib() fails with error 0x8002801c (TYPE_E_REGISTRYACCESS: “Error accessing the OLE registry”).
• DllRegisterServer(): this really depends on how DllRegisterServer() is implemented in the DLL that includes the type library. The default ATL implementation returns the HRESULT of RegisterTypeLib unchanged, so it also returns TYPE_E_REGISTRYACCESS. Other implementations may turn the error into a more generic HRESULT like E_FAIL.
• regsvr32.exe succeeds and shows the message box “DllRegisterServer in D:\ATLDll\Release\atldll.dll succeeded”. Uh? How can it be, if all it does is to call DllRegisterServer? First of all, we can double-check that the registry keys have not been changed. So what happens is that the call to DllRegisterServer failed, but nonetheless regsvr32.exe reported a successful return. This “magic” happens by means of the Shim Technology: if the hosting process is regsvr32.exe, the return value of the RegSetValueEx() API is changed through a shim.

The logic behind the tightening of security permissions on these registry keys should be fairly clear: if any registration of a COM Dll is allowed to overwrite the registry keys related to a system TLB like msxml6.dll (Windows 2003 behavior), the system may misbehave as soon as this Dll is removed. This is one of those scenarios where re-registering msxml6.dll (or another system dll) mysteriously fixed the problem until Windows 2003.

The logic behind the shim in regsvr32.exe is more subtle and has to do with compatibility. Let’s assume we re-register a dll like msxml6.dll by running regsvr32.exe. Since the registration tries to write values to those protected registry keys, the registration would fail. Keep in mind, however, that those registry keys already have those values from the registration that occurred at installation time, when a principal with the TrustedInstaller credentials wrote them. Reporting a failure from regsvr32 would make the user think that something went wrong, which is not the case here. The same behavior takes place if we are registering a custom TLB that happens to embed the definition of the IXMLDOMXxx interfaces.

All right, we came to know the details of type library registration and the “magic” of shims, so it is time to go back to our main topic.

import and importlib

There are essentially 2 ways you can make a type visible within a type library: import and importlib.

import really imports the types in the current .IDL and, as a consequence, in the generated type library (in other words, it does what its name advertises ).

importlib reads the types from a type library and makes them available for type resolution. If type resolution happens successfully, the generated type library will contain a reference to the original type defined in the external type library. Note that importlib can only be used inside the library block of an IDL file.

What happens if a type is referenced by both import and importlib? The MIDL compiler resolves agains the first type, which means the type imported through the import statement (importlib can be used within the library block, whereas import is typically used at the beginning of the IDL file).

With reference to the problem at hand, if we use both “import "ocidl.idl" and importlib(“msxml6.dll”), the generated type library will still embed the IXMLDOMXxx interfaces. This information, however, gives us an easy solution to our problem: use importlib(“msxml6.dll”) without import(“ocidl.idl”). So the following IDL file:

import "oaidl.idl";
//import "ocidl.idl";

[
    uuid(F31AF329-0FE0-4640-80F8-40D187FF4D8B),
    version(1.0),
    helpstring("MyItfLib 1.0 Type Library")
]
library MyItfLib
{
    importlib("stdole32.tlb");
    importlib("stdole2.tlb");
    importlib("msxml6.dll");
    [
        object,
        uuid(BBA99D28-318E-4d69-A835-822EBDCEDA29),
        oleautomation,
        helpstring("IMyItf Interface"),
        pointer_default(unique)
    ]
    interface IMyItf : IUnknown
    {
         [id(1), helpstring("method Load")] HRESULT Load([in] IXmlDOMNode* querySettingsNode);
    };
};

will generate a type library with only the IMyItf interface defined.  IXMLDOMNode is referenced from the external TLB:

Unfortunately, this is not the end of the story . There are special cases (not so special, actually) where this simple approach does not work. Read on…

Forward Declarations and Type Dependencies

Using import without importlib in the previous section did the job. This does not work, however, if we define interfaces outside the library block (forward declaration). For example:

import "oaidl.idl";
//import "ocidl.idl";

[
    object,
    uuid(BBA99D28-318E-4d69-A835-822EBDCEDA29),
    oleautomation,
    helpstring("IMyItf Interface"),
    pointer_default(unique)
]
interface IMyItf : IUnknown
{
    [id(1), helpstring("method Load")] HRESULT Load([in] IXmlDOMNode* querySettingsNode);
};

[
    uuid(F31AF329-0FE0-4640-80F8-40D187FF4D8B),
    version(1.0),
    helpstring("MyItfLib 1.0 Type Library")
]
library MyItfLib
{
    importlib("stdole32.tlb");
    importlib("stdole2.tlb");
    importlib("msxml6.dll");

    interface IMyItf;
};

in this case, since we are referencing IXMLDOMNode outside the library block, the reference to IXMLDOMNode cannot be resolved and we get the following error:

1>.\MyItf.idl(13) : error MIDL2025 : syntax error : expecting a type specification near "IXmlDOMNode"
1>.\MyItf.idl(13) : error MIDL2026 : cannot recover from earlier syntax errors; aborting compilation 

If you are the author of the IDL file, the solution here is pretty easy: avoid the forward declaration and place everything in the library block. Unless you have a complex set of dependencies (for example, interface A uses interface B in some of its methods, and interface B uses interface A in some of its methods), this is doable and effectively addresses the problem.

There is another potential issue though: what if your IDL file needs another type that is defined (either directly or indirectly) in ocidl.idl? If this happens, you need to import ocidl.idl, but by doing that you are also including msxml.idl and hence embedding the IXMLDOMXxx interfaces in your TLB again!!

Here is an example of such an interface (IOleControl is defined directly in ocidl.idl):

[
    object,
    uuid(BBA99D28-318E-4d69-A835-822EBDCEDA29),
    oleautomation,
    helpstring("IMyItf Interface"),
    pointer_default(unique)
]
interface IMyItf : IUnknown
{
    [id(1), helpstring("method Load")] HRESULT Load([in] IXMLDOMNode* querySettingsNode);
    [id(2), helpstring("method InitControl")] HRESULT InitControl([in] IOleControl* pControl);
};

Ok, this is admittedly the trickiest part, so let’s take a deep breath before we go on .

DO_NO_IMPORTS to the rescue

Some of you may legitimately wonder: why do we need to import ocidl.idl to have the definition of IOleControl? Couldn’t we follow the same steps that we used for IXMLDOMNode and use importlib against the type library that defines IOleControl?

Yes, we could. The problem is that there is no type library in the sytem that defines IOleControl. This may seem strange, but there is a reason (there is a reason for everything, isn’t there? ): type libraries are used mainly for type-library (also known as OleAutomation, or Universal) marshaling. If an interface defines its own marshaling, there is no need for a type library. Here is how the registry looks like for IOleControl:

As you can see, there is no TypeLib subkey. So we really need to import ocidl.idl in order to have the definition of IOleControl.

Let’s have a look at how ocidl.idl imports the IXMLDOMXxx interfaces. At the beginning of ocidl.idl we have:

#ifndef DO_NO_IMPORTS
import "oleidl.idl";
import "oaidl.idl";
import "servprov.idl";
import "urlmon.idl";
#endif

and near the beginning of urlmon.idl we have:

import "objidl.idl";
import "oleidl.idl";
import "servprov.idl";
import "msxml.idl";

msxml.idl defines the IXMLDOMXxx interfaces. So it seems that we may be able to achieve our goal by using the preprocessor definition DO_NO_IMPORTS. If we do that (best way is to specify it in the “Preprocessor Definitions” test box in the .IDL file properties, equivalent to the /D command-line option, instead of using #define in the .IDL file), however, we get the following output from the MIDL compiler:

1>C:\Program Files\Microsoft SDKs\Windows\v6.0A\include\oaidl.idl(64) : error MIDL2025 : syntax error : expecting a type specification near "ULONG"
1>C:\Program Files\Microsoft SDKs\Windows\v6.0A\include\oaidl.idl(65) : error MIDL2026 : cannot recover from earlier syntax errors; aborting compilation

Note that the errors are generating while compiling oaidl.idl, which is imported before ocidl.idl. The reason is clear if we look near the beginning of oaidl.idl:

#ifndef DO_NO_IMPORTS
import "objidl.idl";
#endif

Since objidl.idl defines some basic types like ULONG, we need to include it explicitly before objidl.idl. Once we do this, we still get errors because of unresolved types. We can fine-tune import of other IDL files until we get to this:

import "wtypes.idl";
import "unknwn.idl";
import "objidl.idl";
import "oaidl.idl";
import "oleidl.idl";
import "ocidl.idl";

With this sequence of imports we still get a MIDL compiler error:

1>C:\Program Files\Microsoft SDKs\Windows\v6.0A\include\ocidl.idl(1830) : error MIDL2025 : syntax error : expecting a type specification near "IBindHost"
1>C:\Program Files\Microsoft SDKs\Windows\v6.0A\include\ocidl.idl(1830) : error MIDL2026 : cannot recover from earlier syntax errors; aborting compilation 

IBindHost is defined in urlmon.idl, which is imported conditionally in ocidl.idl (see first code snippet in this section). However, importing urlmon.idl before ocidl.idl is not a solution, because urlmon.idl imports msxml.idl, as shown by this import sequence at the beginning of urlmon.idl:

import "objidl.idl";
import "oleidl.idl";
import "servprov.idl";
import "msxml.idl";

So here we are apparently at a dead end: we would need to import urlmon.idl because ocidl.idl needs the definition of IBindHost, but if we do that we also import msxml.idl, which will cause the embedding of the IXMLDOMXxx interfaces in our type library.

One possible way out here is to create your own custom IDL file, say MyBindHost.idl, which includes IBindHost and its dependencies, and then to import it in your IDL file in place of urlmon.idl:

import "wtypes.idl";
import "unknwn.idl";
import "objidl.idl";
import "oaidl.idl";
import "oleidl.idl";
import "mybindhost.idl";
import "servprov.idl";
import "ocidl.idl";

This works and the IDL file compiles successfully to a TLB which does not include the definition of the IXMLDOMXxx interfaces. The TLB does include the definition of IOleControl, but this is not an issue: since the interface is not declared with the dual or oleautomation attributes, it won’t register itself as the marshaler of IOleControl.

A suitable MyBindHost.idl is attached at the end of this post.

IUnknown is a special case

At this point you may wonder about the interface IUnknown, which seems to have a different behavior: we need IUnknown in our IDL because it is the base interface of our interface:

...
interface IMyItf : IUnknown
{
    ...
};

IUnknown is defined in unknwn.idl, which we are importing either directly or indirectly. IUnknown is also made available through importlib of stdole32.tlb and stdole2.tlb. In such a case, you would expect that the first definition is matched, and so we should see IUnknown in the generated type library, but this is not the case.

The reason is that the MIDL considers IUnknown (and potentially other interfaces) differently, and therefore a reference to it is generated in these cases, instead of embedding IUnknown in the generated type library.

Summary

Some key points of this post:

• If you are authoring IDL files, you need to understand the difference between referencing a type in the type library you generate, and embedding it.
• It is very important to avoid embedding system types into your own type library. A common case when this may happen is with the IXMLDOMXxx interfaces.
• In Vista and later operating systems, permissions on registry keys prevent the association of a system interface with a different type library. However, type library registration may fail if not done through regsvr32.exe.
• If your solution consists of several type libraries, the same principles apply: you should define a type in one type library only, and reference it from other type libraries by using importlib. If this causes circular references, factor out the involved types into one type library and reference it from the other type libraries.

MyBindHost.idl