Hosting two instances of the Scribe AX adapter (ScribeAxServiceHost) on the same server (to connect to two AOS instances)

When the Scribe AX adapter server component (the Windows service, Scribe AxServiceHost, for adapter version 1.1 with Scribe Insight 7.0.1) is set up, we do a few changes to its configuration file (Scribe.AxServiceHost.exe.config).

Within the <AxServiceHost.Properties.Settings> configuration section, there is a section that says –

<setting name="aosServer" serializeAs="String">
<value>[your AX application instance]@[your server name]:[your TCP/IP port number]</value>
</setting>

Here we edit the text within the  <value>  tags, and replace with the actual values (the placeholder text blocks are self-explanatory and the actual values can be retrieved by logging into the AOS server and going to Start -> Programs -> Administrative Tools -> Microsoft Dynamics AX 2009 Server Configuration). Then, we go to Start -> Programs -> Administrative Tools -> Services and restart the Scribe AxServiceHost service. Once we restart the service our new settings take effect.

This suffices when we need to connect to only one AOS instance (you might have easily guessed that, since the Scribe.AxServiceHost.exe.config file only allows one instance of the <setting name="aosServer" serializeAs="String"> tag). If there is a need to connect to multiple AOS instances that reside on the same server then we have a problem. Also, we can not have the Scribe AxServiceHost service on a server different from the AOS (for more details, look at my earlier post here). So, if you are thinking that we can have multiple servers running the Scribe AxServiceHost service each referring to a different AOS, then don’t, as that won’t work.

So, if you need to connect Scribe to multiple AOS instances running on the same server, the solution is to set up multiple instances of the Scribe AxServiceHost Windows service, each referring to a different AOS instance. To do this, log into the server hosting the multiple AOS instances with administrative privileges. Open Windows Explorer and navigate to the folder that contains the files for the Scribe AxServiceHost. By default this is C:\Program Files (x86)\Scribe\Dynamics AX Server on a 64-bit operating system and C:\Program Files\Scribe\Dynamics AX Server on a 32-bit one. Copy the folder ScribeAX Service and paste it in the same location. A new folder named ScribeAX Service - Copy will be created below the existing folder with name ScribeAX Service. Rename the new folder to something that will help you identify the AOS instance you will use it to connect to. We named it ScribeAX Service - 10, suffixing our internal identifier for the AOS instance (10). Navigate within the new folder and open the file Scribe.AxServiceHost.exe.config in Notepad with Administrative privileges. Now, the Scribe AxServiceHost is just a Windows service hosting the WCF service that the Scribe Workbench (or integration packages) connect to. We need to make another instance of this WCF service running on this server. To do this, we have to run this WCF service on ports other than the ones on which the already configured instance of Scribe AxServiceHost is running. Locate the tag <services> within the tag <system.serviceModel>. You should see the configuration of a WCF service with name AxServiceHost.AxaptaService within. There will be four endpoints configured (each with a <endpoint> tag) and a host setting (with a <host> tag). The first two endpoints (for wsHttpBinding) will not need any changes as there is not port specified here. The third endpoint (for TCP binding) looks like this –

<endpoint address="net.tcp://Your server name/AxServiceHost/AxaptaService/"
binding="netTcpBinding" bindingConfiguration="netTcpBinding_ScribeService"
contract="AxServiceHost.IAxaptaService" />

By default, if you do not specify the port for TCP binding the 808 port is used. So, change this entry to something like this, to explicitly specify a new port –

<endpoint address="net.tcp://Your server name:8732/AxServiceHost/AxaptaService/"
binding="netTcpBinding" bindingConfiguration="netTcpBinding_ScribeService"
contract="AxServiceHost.IAxaptaService" />

Here, I have used the port 8732, however, you can use any available port of your choice.

Now, look at the next endpoint. This will be the one for the MEX (metadata exchange) for the above TCP binding endpoint. This is used by clients to retrieve the WSDL for your web service. It should look like this –

<endpoint address="net.tcp://Your server name/AxServiceHost/AxaptaService/mex"
binding="mexTcpBinding" bindingConfiguration="" contract="IMetadataExchange" />

This should be edited to specify the same port as the one used above. So, I edited it to look like this –

<endpoint address="net.tcp://Your server name:8732/AxServiceHost/AxaptaService/mex"
binding="mexTcpBinding" bindingConfiguration="" contract="IMetadataExchange" />

Now, look at the <host> tag below. There should be a <baseAddresses> tag in it, containing a base address entry that looks like this –

<add baseAddress="http://Your server name:8731/AxaptaService/" />

Here, edit the entry to change the port to an available port. Do not use the port specified above for the TCP binding. Here is what I used –

<add baseAddress="http://Your server name:8733/AxaptaService/" />

With these changes done, you are ready to run your WCF service alongside the existing one. There is just one more change to be done in the configuration file – you need to specify the new AOS instance that you wish to connect to. Locate the tag <setting name="aosServer" serializeAs="String">. Within the tag, we specify the AOS instance details as follows –

<value>Your AOS instance name@Your AOS server:Your AOS instance port</value>

I edited mine to look like this –

<value>MyAOS10@MyAOSServer:2713</value>

Save the Scribe.AxServiceHost.exe.config and close Notepad. Now, open a Command Prompt with Administrative privileges (Start -> Programs -> Accessories -> Right-click on Command Prompt -> Select Run as Administrator). Change the directory to C:\Windows\Microsoft.NET\Framework64\v2.0.50727 (for 64-bit operating system) or C:\Windows\Microsoft.NET\Framework\v2.0.50727 (for 32-bit operating system). Use the command below to do that –

For 64-bit operating system –

cd "C:\Windows\Microsoft.NET\Framework64\v2.0.50727"

or for 32-bit operating system –

cd "C:\Windows\Microsoft.NET\Framework\v2.0.50727"

Now, run the following command to install the new copy of the Scribe AxServiceHost as a Windows service.

For 64-bit operating system –

installutil.exe "C:\Program Files (x86)\Scribe\Dynamics AX Server\ScribeAX Service - 10\Scribe.AxServiceHost.exe"

or for 32-bit operating system –

installutil.exe "C:\Program Files\Scribe\Dynamics AX Server\ScribeAX Service - 10\Scribe.AxServiceHost.exe"

Replace the ScribeAX Service - 10 here, with the name of the folder where you copied the existing ScribeAX Service folder in the first step. It will ask you for the user account details under which you wish to run the Windows service. Specify a local/domain account here. The Windows service that gets installed will run under this user account. If you are using Windows authentication for Scribe, this account will need access to your Scribe SQL Server database (by default, the SCRIBEINTERNAL database).
Now, if you go to Start -> Programs -> Administrative Tools -> Services (or refresh it if it’s already open), you should see a new Windows service named, AxService. You can verify the location by right-clicking on it and checking the “Path to Executable” section of the dialog box that opens.

Now, simply start the Windows service. In Internet Explorer, browse to http://Your server name:8733/AxaptaService/ (replace the Your server name:8733 with your server name for the AxService and port – the one specified for the <base address>). This should give you the web service details page with the WSDL link.
You can then use Scribe Workbench and create a connection with the Microsoft Dynamics AX Adapter using the URL http://Your server name:8733/AxaptaService/.

If you repeat this process once more you will get an error from InstallUtil.exe saying "System.ComponentModel.Win32Exception: The specified service already exists". This is because the InstallUtil.exe will try to install a service with the name AxService and that one already exists. I’m still trying to figure out how to pass a service name to InstallUtil.exe, so that we can have as many instances as we want, and not just two. Since, the default Scribe setup installs the same executable as ScribeAxServiceHost, and not AxService, it means that it supports specifying a custom service name. But that should be a custom parameter for the InstallUtil.exe that I’m not aware of as of now. That will be subject of another post, soon…

For information of InstallUtil.exe, go here.