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.
- Windows Operating System
- Microsoft .NET Framework 4.8 or later
- Network access from the agent to the SOAP service endpoint
- 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
.wsdland.xsdextensions. Every.wsdland.xsdfile 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
}
}
| Setting | Description |
|---|---|
| port | Controls the port that the agent listens on. This port must be open and available to the Intelligence Hub connecting to the agent. |
| token | Random security token created by the agent. This token must be applied to the Intelligence Hub WCF SOAP connection settings to authenticate the hub. |
| subjectName | Controls the certificate/key used by the agent secure websocket. Default: HighByte WCF SOAP Agent |
| settings.endpoint | The 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.addressOverride | Replaces 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>