I've released an updated version of my popular Dynamics 365 Configuration Data Mover utility that was built with .Net 4.7 to address the new requirement to use TLS 1.2 (or better) for connections to Dynamics 365 online instances as described in this entry on the Microsoft Dynamics 365 team blog: https://blogs.msdn.microsoft.com/crm/2017/09/28/updates-coming-to-dynamics-365-customer-engagement-connection-security.

This upgrade is fully compatible with existing job files.

Getting the Dynamics 365 Configuration Data Mover

The source code is available in my GitHub repository here.

A compiled version can be downloaded here.

I was recently asked to add a feature to my Dynamics 365 Configuration Data Mover to enable connections through a proxy server. Because the tool is a .Net application, proxy server connections can be configured directly in the AlexanderDevelopmentConfigDataMover.exe.config file. For example, if you want to use the default Internet Explorer proxy settings, just add the following values inside the element:

<system.net>
  <defaultproxy enabled="true"> 
    <proxy usesystemdefault="true"/> 
  </defaultproxy> 
</system.net>

For more information on proxy settings, take a look at this Microsoft overview on .Net proxy configuration.

Several months ago I discussed an approach for passing notifications from local applications to the Dynamics 365 web client through a message listener process that runs on an end user's PC and shared some sample code for how to implement it.

Recently I used this approach to establish communication between Dynamics 365 web resources and a fingerprint reader attached to a local PC. The actual coding was fairly simple, but I did run into a problem that I did not encounter when I built my original proof-of-concept message listener because I was accessing Dynamics 365 via HTTPS as opposed to HTTP like I had been in my on-prem development sandbox. Because mixed content can be a security risk, modern browsers typically block pages that are accessed via HTTPS from loading scripts over HTTP, which is how my listener process was running.

In order to make my listener process accessible via HTTPS, I did the following:

1. Generated a self-signed SSL certificate to represent a root certificate authority.
2. Generated an SSL certificate signed by my root CA to encrypt communication with my message listener process.
3. Added the root SSL certificate from step #1 as a trusted root certificate on the local PC.
4. Added the SSL certificate from step #2 to the personal certificate store on the local PC.
5. Bound the SSL certificate from step #2 to the port my listener process uses.

Generating the certificates

This blog post has detailed steps I followed to generate self-signed certificates with PowerShell's New-SelfSignedCertificate cmdlet. In the past I have used OpenSSL to generate self-signed certificates, and while OpenSSL would definitely work here, I found the PowerShell approach to be much easier for my initial development purposes.

(A note on security - As I look at making this solution fully ready for production, I need to do some further investigation into the security implications of using self-signed certificates. Because I am only using them to enable communication with a process running on the local PC, I think the risks are minimal as long as the root certificate is kept secure.)

Installing the certificates

Once you have generated your two SSL certificates, you need to install them on the local PC. If you followed the directions from the blog post above to generate your certificates, you should have a public certificate for your root CA as a .cer file and a private certificate to use for the application as a .pfx file.

To install the root certificate as a trusted root certificate authority, do the following:

1. Double-click public certificate (.cer file) for the root CA you generated. The certificate properties window will open. Click "install certificate."
2. The certificate import wizard will open. Select "local machine" and click next.
3. You may be presented with a confirmation dialog asking if you "want to allow this app to make changes to your device." If so, click yes.
4. On the next screen, select "place all certificates in the following store" and click browse.
5. Select "trusted root certification authorities."
6. Verify the certificate store input shows "trusted root certification authorities" and click next.
7. Click finish.
8. You will receive a success message. Click OK to close it.
9. Close the certificate properties window.

To install the SSL certificate that will encrypt communication with the message listener, do the following:

1. Double-click private certificate (.pfx) for the application certificate CA you generated. The certificate import wizard will open. Select "local machine" and click next.
2. You may be presented with a confirmation dialog asking if you "want to allow this app to make changes to your device." If so, click yes.
3. You will see the name of your .pfx file in the file name input box. Click next.
4. Enter the password for the .pfx file and click next.
5. On the next screen, select "place all certificates in the following store" and click browse.
6. Select "personal."
7. Verify the certificate store input shows "personal" and click next.
8. Click finish.

Binding the application SSL certificate to the message listener port

Once you have installed the certificates on the local PC, you can bind the application SSL certificate to the port on which the message listener is listening. I am using Windows 10, but the directions outlined in this Microsoft document for Windows Vista worked for me. Presumably they will also work for Windows 7 and 8.

If you don't feel like reading the entire document, basically you can use the netsh command to encrypt all requests on a specific port for a specific application using a specific SSL certificate. Here's how to configure it:

1. Get the thumbprint from the SSL certificate you installed in the "personal" store following the instructions here - https://docs.microsoft.com/en-us/dotnet/framework/wcf/feature-details/how-to-retrieve-the-thumbprint-of-a-certificate.
2. Get the application id from your message listener application. If your message listener is a .Net application, you would use the "Assembly: Guid" value from your application's AssemblyInfo file.
3. Open a command prompt as an administrator and execute the following command: netsh http add sslcert ipport=0.0.0.0:9345 certhash=CC5F7BF58FD666EEC844C1B949E9661267A8A310 appid={b31bee72-c2ac-411e-959b-adbd25bba2cf} You will need to substitute your specific values for "ipport," "certhash" and "appid."
4. Verify your configuration works by starting your message listener and then making an HTTPS request.

Assuming everything works, you should now be able to access your local message listener process from your Dynamics 365 web resources. If you want to use the message listener on other PCs, you don't have to regenerate new certificates. You can just install the same certificates and run the same netsh command on every PC where the listener application will run.

What do think about this approach? Are there any real-world scenarios where it would be useful for you?

In part one of this series, I discussed an approach for passing notifications from local applications to the Dynamics 365 web client through a message listener process that runs on an end user's PC. Today I will show the code I used to build the message listener and the code to consume notifications in Dynamics 365.

The message listener

My message listener is a lightweight web server built in C# using the "WebServer" class from this blog post.

I've made a couple of small modifications to the original web server code to enable cross-origin resource sharing (CORS). Otherwise requests from the Dynamics 365 web resource would fail because the sites have different origins. Here's my updated WebServer class:

/*
 * The MIT License (MIT)
 * 
 * Copyright (c) 2013 David's Blog (www.codehosting.net) 
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
 * associated documentation files (the "Software"), to deal in the Software without restriction, 
 * including without limitation the rights to use, copy, modify, merge, publish, distribute, 
 * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is 
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all copies or 
 * substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
 * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
 * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
 * DEALINGS IN THE SOFTWARE.
*/

//The code below is mostly taken from https://codehosting.net/blog/BlogEngine/post/Simple-C-Web-Server
//I've added the headers to enable CORS requests.

using System;
using System.Net;
using System.Threading;
using System.Linq;
using System.Text;

namespace SimpleWebServer
{
    public class WebServer
    {
        private readonly HttpListener _listener = new HttpListener();
        private readonly Func<HttpListenerRequest, string> _responderMethod;

        public WebServer(string[] prefixes, Func<HttpListenerRequest, string> method)
        {
            if (!HttpListener.IsSupported)
                throw new NotSupportedException(
                    "Needs Windows XP SP2, Server 2003 or later.");

            // URI prefixes are required, for example 
            // "http://localhost:8080/index/".
            if (prefixes == null || prefixes.Length == 0)
                throw new ArgumentException("prefixes");

            // A responder method is required
            if (method == null)
                throw new ArgumentException("method");

            foreach (string s in prefixes)
                _listener.Prefixes.Add(s);

            _responderMethod = method;
            _listener.Start();
        }

        public WebServer(Func<HttpListenerRequest, string> method, params string[] prefixes)
            : this(prefixes, method) { }

        public void Run()
        {
            ThreadPool.QueueUserWorkItem((o) =>
            {
                //Console.WriteLine("Webserver running...");
                try
                {
                    while (_listener.IsListening)
                    {
                        ThreadPool.QueueUserWorkItem((c) =>
                        {
                            var ctx = c as HttpListenerContext;
                            try
                            {
                                string rstr = _responderMethod(ctx.Request);
                                byte[] buf = Encoding.UTF8.GetBytes(rstr);
                                if (ctx.Request.HttpMethod == "OPTIONS")
                                {
                                    ctx.Response.AddHeader("Access-Control-Allow-Headers", "Content-Type, Accept, X-Requested-With");
                                    ctx.Response.AddHeader("Access-Control-Allow-Methods", "GET, POST");
                                    ctx.Response.AddHeader("Access-Control-Max-Age", "1728000");
                                }
                                ctx.Response.AddHeader("Access-Control-Allow-Origin", "*");
                                ctx.Response.ContentLength64 = buf.Length;
                                ctx.Response.OutputStream.Write(buf, 0, buf.Length);
                            }
                            catch { } // suppress any exceptions
                            finally
                            {
                                // always close the stream
                                ctx.Response.OutputStream.Close();
                            }
                        }, _listener.GetContext());
                    }
                }
                catch { } // suppress any exceptions
            });
        }

        public void Stop()
        {
            _listener.Stop();
            _listener.Close();
        }
    }
}

Here is the code for a proof-of-concept application that runs the listener web server. It allows you to enter messages directly on the command line for easy testing, but ideally you would configure your message listener to run as a service or in some other mostly headless fashion. You will need the JSON.Net library to compile this code.

using System;
using System.Collections.Generic;
using System.Net;
using SimpleWebServer;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

namespace CrmIntegrationServer
{
    class Program
    {
        static List<string> _messages;

        static void Main(string[] args)
        {
            _messages = new List<string>();
            WebServer ws = new WebServer(ProcessRequest, "http://localhost:8080/");
            ws.Run();
            Console.WriteLine("Demo CRM integration server. Type 'CTRL+C' to exit.");
            while (true)
            {
                Console.WriteLine("Enter your message:");
                string receivedline = Console.ReadLine();
                _messages.Add("{\"data\":\""+receivedline+"\"}");
            }
        }

        public static string ProcessRequest(HttpListenerRequest request)
        {
            string receviedmessage = string.Empty;
            string response = string.Empty;
            if (request.HasEntityBody)
            {
                using (System.IO.Stream body = request.InputStream) // here we have data
                {
                    using (System.IO.StreamReader reader = new System.IO.StreamReader(body, request.ContentEncoding))
                    {
                        receviedmessage = reader.ReadToEnd();
                    }
                    JObject reqobject = JObject.Parse(receviedmessage);
                    switch (reqobject.Value<string>("action").ToUpper())
                    {
                        case "QUEUE":
                            string messagebody = reqobject["messagebody"].ToString(Formatting.None);
                            _messages.Add(messagebody);
                            response =  "{\"result\":\"success\"}";
                            break;
                        case "READ":
                            response = JsonConvert.SerializeObject(_messages);
                            _messages.Clear();
                            break;
                    }
                }
            }
            return response;
        }
    }
}

The Dynamics 365 client JavaScript

Finally, here's the code for the Dynamics 365 web resource that reads the messages. I have it set to poll for new messages every 100 milliseconds, which seems plenty fast, but you can experiment to find the value that works best for you. Because it's just making local requests and not putting additional load on your Dynamics 365 org, you don't need to worry about negatively impacting performance.

<html>  
<head>  
    <title>listener demo </title>
    <script src="ClientGlobalContext.js.aspx" type="text/javascript"></script>
    <script src="https://code.jquery.com/jquery-2.2.4.min.js" type="text/javascript"></script>
    <script>
	var intervalId = null;
	var openrequest = false;
	var requestData = function(){
		if(!openrequest){
			openrequest = true;
			var request = $.ajax({
				url: 'http://localhost:8080',
				type: 'POST',
				contentType: 'application/json',
				dataType: "json",
				data: JSON.stringify({action:'read'})
			});
			request.done(function( msg ) {
				openrequest = false;
				for(var i=0;i<msg.length;i++){
					$('#messageDiv').append(JSON.parse(msg[i]).data + '<br />')
				}
			});
			request.fail(function( jqXHR, textStatus ) {
				openrequest = false;
				clearInterval(intervalId);
				$('#messageDiv').append('Request failed: ' + textStatus );
			});
		}
	}
	var intervaltime = 100;
	$(function(){
		intervalId = setInterval(requestData, intervaltime);
    });
	
    </script>
</head>  
<body>  
	<div id='messageDiv' />
</body>  
</html>

Final thoughts

1. You could modify the my proof-of-concept listener application to support outbound integrations with local workstation resources. For example, if you want to start a local program based on a Dynamics 365 form event, you post a specific kind of JSON request to the listener from Dynamics 365, and then the listener would start the program running.
2. Keeping the queued messages as a list of strings is probably not be the best long-term approach, especially if you have different types of messages passing through the listener that you want to handle differently. In that case, you'd want to store the messages in a data structure that allows you to retrieve just a particular kind of message.
3. The list of queued messages in my proof-of-concept application does not persist if the listener process stops running. This probably isn't a big deal because the whole idea of the message listener is to facilitate real-time communication, but I wanted to make the point explicitly clear.

What do you think about this approach? Can you see yourself using it on your projects? Let us know in the comments!

One problem that comes up from time to time on Dynamics 365 Customer Engagement projects is how to receive notifications from an application running on a user's local PC. Although the Unified Service Desk (USD) interface supports a variety of ways for Dynamics 365 to interact with local applications, the out-of-the-box web interface does not. Today, I will present an approach that uses something similar to the Dynamics 365 USD generic listener adapter.

The USD generic listener adapter is essentially just a lightweight web server that runs on the local workstation. When it receives GET requests with certain query string parameters, it raises events in the USD application that trigger various predefined actions. It was originally intended for testing CTI configuration in USD, and although Microsoft officially calls it a "testing tool," it's actually an easy-to-use (and free) component that you can use to trigger all sorts of automations in USD.

A web client message listener

My approach to a message listener for the web client also uses a lightweight web server built in C# that runs on the local workstation. When an application wants to pass a message to Dynamics 365, it can post a JSON object to the listener, where it will be queued for later retrieval by custom JavaScript code in Dynamics 365. When the queued messages are retrieved from the listener, they are also purged from the queue so each request returns only new messages.

Here's what the JSON objects look like:

//POSTING A NEW MESSAGE
{
  "action":"queue",
  "messagebody":{
      "data":"MESSAGE TO PASS TO CRM . . ."
  }
}

//REQUESTING QUEUED MESSAGES
{
  "action":"read"
}

//QUEUED MESSAGES
[
  {"data":"MESSAGE FOR CRM 1"},
  {"data":"MESSAGE FOR CRM 2"},
  {"data":"MESSAGE FOR CRM 3"}
]

Once the messages are retrieved in Dynamics 365, they can be processed however you like. In my next post, I'll show the code to make the approach work. Until then, happy coding!

About two weeks ago a commenter mentioned that my Configuration Data Mover wasn't working with UK Dynamics 365 online organizations that had been created since the change to the orgname.crm11.dynamics.com URL structure. I've released a new version with an updated SDK reference that has resolved the issue.

If you are using an older version of the data mover and you are working with online orgs in a new region, you may want to go ahead and upgrade to the latest version here.

I've released an updated version of my popular CRM Configuration Data Mover utility that fixes a small annoyance in the previous version where you could open multiple instances of the set connection, about and check for upgrade windows. This upgrade is fully compatible with existing job files.

Getting the Dynamics 365 Configuration Data Mover

The source code is available in my GitHub repository here.

A compiled version can be downloaded here.