WCF SOAP Agent

The WCF SOAP Agent uses Windows Communication Foundation (WCF) to call operations on a SOAP service described by a WSDL. The requirements for the agent are as follows.

  1. Windows Operating System
  2. Microsoft .NET Framework 4.8 or later
  3. Network access from the agent to the SOAP service endpoint
  4. The WSDL and XSD files exported from the SOAP service

The Intelligence Hub communicates with the agent over a secure websocket (wss) connection that requires a TLS certificate. To use a self-signed certificate and private key, run the following command from an elevated command prompt to install them into the LocalMachine\Personal certificate store.

intelligencehub-wcf-soap.exe -installcert

To use a different certificate, import the certificate and private key into the LocalMachine\Personal certificate store and grant the account running the agent read access to the private key. Then set subjectName in settings.json to the certificate’s Subject Common Name (CN) and restart the agent.

Export the WSDL

The agent loads the service description from the wsdl folder in the agent directory at startup. Before running the agent, export the service’s WSDL into this folder.

Download the WSDL

WCF services built on .NET 4.5 or later serve the full description, including schemas, as a single file. To download it, run the following command with the service address.

intelligencehub-wcf-soap.exe -downloadwsdl https://server/Service.svc

The agent requests the address with ?singleWsdl appended and saves the WSDL to the wsdl folder in the agent directory as <ServiceName>.wsdl. The folder is created if it doesn’t exist. The command exits after the download and doesn’t start the agent.

The download uses the Windows account running the command to authenticate with the service. Run the command with an account that has access to the service.

Manually Download the WSDL

For services that don’t support ?singleWsdl, export the full set of files with the Microsoft ServiceModel Metadata Utility Tool: svcutil.exe /t:metadata <service url>.

WSDL Folder Requirements

The wsdl folder must contain exactly one exported service description:

  • Files must use the .wsdl and .xsd extensions. Every .wsdl and .xsd file in the folder is loaded.
  • Exactly one WSDL file can define the service.
  • Every XSD file imported by the WSDL must be present. Imports are resolved from the files in the folder.

Only document/literal SOAP services are supported. If the selected binding uses the RPC style, the agent fails to start. Operations that don’t use document/literal messages are skipped and logged. If the WSDL can’t be loaded, the agent logs the error and stops.

Agent Settings

On the first run the agent creates a settings.json file. The file contains the following. Note any settings changes require restarting the agent.

{
	"port": 45490,
	"token": "randomtoken",
	"subjectName": "HighByte WCF SOAP Agent",
	"settings": {
		"endpoint": null,
		"addressOverride": null
	}
}
SettingDescription
portControls the port that the agent listens on. This port must be open and available to the Intelligence Hub connecting to the agent.
tokenRandom security token created by the agent. This token must be applied to the Intelligence Hub WCF SOAP connection settings to authenticate the hub.
subjectNameControls the certificate/key used by the agent secure websocket. Default: HighByte WCF SOAP Agent
settings.endpointThe WSDL port (or binding) name of the endpoint to use. When empty, the agent uses the first endpoint in the WSDL and logs its name. Set this when the WSDL defines more than one endpoint, for example to use an HTTP endpoint instead of a TCP endpoint. If the name isn’t found, the agent logs the available endpoints and stops.
settings.addressOverrideReplaces the endpoint address defined in the WSDL. Use this when the WSDL address uses a host name the agent can’t reach. For example, https://campaignserver.mydomain.com/CampaignManager/Service.svc.

Run the Agent

The agent runs as a standalone application, by running the intelligencehub-wcf-soap.exe OR as a Windows service. When running standalone, it’s recommended to run the executable with admin level permissions. To install as a service, run the following command. InstallUtil is found in the .NET installation directory: %windir%\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe

installutil intelligencehub-wcf-soap.exe

NOTE: When the connection uses Service Account authentication, the agent calls the SOAP service with the Windows account the agent runs under. Run the agent with an account that has access to the service.

To optionally control the service name, using the following syntax.

installutil /serviceName="myServiceName" /displayName="myDisplayName" intelligencehub-wcf-soap.exe

Diagnostics Logging

The WCF SOAP Agent includes detailed diagnostics to analyze read and write performance, including the time taken by each operation call. The agent uses NLog to control log retention policy and verbosity. To control diagnostics change the intelligencehub-wcf-soap.exe.config file.

Add the following configuration to the file, save the file, and restart the agent. Diagnostics logs will be included in the console output and in the log file.

If the agent is running as a Windows Service, the service account must also have local file system access to write the diagnostics file locally. Otherwise, the local log file will not be written.

The default logging configuration is shown below.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
	<configSections>
		<!-- Register NLog as a configuration section -->
		<section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog" requirePermission="false" />
	</configSections>
	<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
		  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<!-- Define targets (where logs are written) -->
		<targets>
			<!-- File target 3 files up to 100MB each -->
			<target xsi:type="File"
					name="logfile"
					fileName="intelligencehub.log"
					archiveFileName="intelligencehub.{#}.log"
					archiveNumbering="Rolling"
					archiveAboveSize="104857600"
				maxArchiveFiles="3"
				layout="${date:format=dd-MM-yyyy hh\:mm\:ss} | ${level} | Agent | ${message}" />
			<target xsi:type="Console" name="console" layout="${date:format=dd-MM-yyyy hh\:mm\:ss} | ${level} | Agent | ${message}" />
		</targets>

		<!-- Define rules (what gets logged and where) -->
		<rules>
			<!-- Log all levels to the file -->
			<logger name="*" minlevel="Trace" writeTo="logfile" />
			<logger name="*" minlevel="Trace" writeTo="console" />
		</rules>
	</nlog>
	<startup>
		<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8"/>
	</startup>
</configuration>