Write a custom Azure-aware plug-in

In this article

Writing a plug-in that works with Azure is similar to writing any other Dynamics 365 Common Data Service plug-in. However, in addition to invoking any desired web service methods, the plug-in must include code to initiate posting the execution context to the Azure Service Bus.

Plug-in design considerations

For a plug-in that executes synchronously, the recommended design is for the plug-in to send a message to Azure for the purpose of retrieving information from a listener application or other external service. Use of a two-way or REST contract on the Azure Service Bus endpoint allows a data string to be returned to the plug-in.

It is not recommended that a synchronous plug-in use the Azure Service Bus to update data with an external service. Problems can arise if the external service becomes unavailable or if there is a lot of data to update. Synchronous plug-ins should execute fast and not hold up all logged in users of an organization while a lengthy operation is performed. In addition, if a rollback of the current core operation that invoked the plug-in occurs, any data changes made by the plug-in are undone. This could leave Dynamics 365 and an external service in an unsynchronized state.

Note that it is possible for synchronous registered plug-ins to post the execution context to the Azure Service Bus.

Write the plug-in code

In the following sample plug-in code has been added to obtain the Azure service provider and initiate posting the execution context to the service bus by calling Execute(EntityReference, IExecutionContext). Tracing code has been added to facilitate debugging of the plug-in because the plug-in must run in the sandbox.

You can query available service endpoints for your environment using a GET request to Web API using your browser with a query like this: [organization Uri]/api/data/v9.0/serviceendpoints?$select=name,description,serviceendpointid

In your plug-in code, you can update the writeable data in the context before initiating the post. For example, you can add a key/value pair to the shared variables in the context.

Plug-in registration

There are a few restrictions when you register a Azure aware custom plug-in. The plug-in must be registered to execute in the sandbox. Because of this, the plug-in is limited to calling IOrganizationService methods, Azure solution methods, or accessing a network using a web client. No other external access, such as access to a local file system, is allowed.

For a plug-in registered to execute in asynchronous mode, this also means that the order of plug-in execution compared to other asynchronous plug-ins is not guaranteed. In addition, asynchronous plug-ins always execute after the Dynamics 365 core operation.

Handle a failed service bus post

The expected behavior from a failed service bus post is dependent on whether the plug-in was registered for synchronous or asynchronous execution. For asynchronous plug-ins, the system job that actually posts the execution context to the service bus will retry the post. For a synchronous registered plug-in, an exception is returned. More information Management and Notification of Run-time Errors

Important

For asynchronous registered plug-ins only, when the asynchronous job that posts to the Azure Service Bus is retried after a post failure, the entire plug-in logic is executed again. Because of this, don’t add any other logic to the custom Azure aware plug-in other than just modifying the context and posting to the service bus.

For a plug-in registered to execute asynchronously, the RemoteExecutionContext contained in the body of the message that is sent over the service bus includes a OperationId property and a OperationCreatedOn property. These properties contain the same data as the AsyncOperationId and CreatedOn attributes of the related System Job (AsyncOperation) record. These additional properties facilitate sequencing and duplicate detection if the Azure Service Bus post must be retried.