Soap API via Visual Studio and C#
An example of how to call the SOAP API using C#
Prerequisites
For this demonstration we are using Visual Studio 2017, please refer to the 2015 guide if you’re using an older version of visual studio. We are going to walk through setting up a simple solution with a few basic components to call the service.
1) Setup the solution
For this demo we are going to create a .net core console application which calls into the W2 Global Data WCF services using the visual studio auto service creation helpers.
1.1 From the Start page of visual studio click on File -> New -> Project…
1.2 Create a .net core console application and give it a sensible name, we chose “W2GlobalDataDemo2017”.
1.3. Edit the program.cs file to remove the pre-populated line.
Console.WriteLine(“Hello World!”);
1.4. Add a new file and class to the console application and call it “W2Client”.
2) Add the service reference
Now we need to add a web service reference for the W2 API.
2.1 Right click on the console project in solution explorer, hover over ‘add’ and then left click on the ‘Connected Service’ option.
2.2 You should see a screen like this:
If you do not see the option to add a WCF web service reference you may need to get a visual studio extension for WCF web services.
2.3 You should now see the configure WCF Web Service Reference screen.
Add the following Uri to the Uri box
https://apiv3-uat.w2globaldata.com/service.svc?wsdl
and click on go. After the service is done loading change the namespace to W2GlobalDataService and click on OK
2.4 This will then load some references from nuget and setup scaffolding
2.5 It will add a new folder and reference.cs file for the WCF scaffolding code. Reference.cs will hold a class that has been auto-generated based on available WSDL information from the W2 Global Data Web Service.
2.6 Replace the code in the W2Client class with the following. The using statement W2GlobalDataService is based on the namespace that was provided when creating the WCF service using the scaffolder.
NOTE: You will need to replace the Api Key and the Client Reference with your own.
namespace W2GlobalDataDemo2017
{
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using W2GlobalDataService;
internal class W2Client
{
public async Task SanctionsCheck(string nameQuery, bool isSandbox = false)
{
// Create a client for calling the service.
var proxy = new ServiceClient();
// build a request object to send to the service
var serviceRequest = BuildSanctionsServiceRequest(nameQuery, isSandbox);
var response = await proxy.KYCCheckAsync(serviceRequest);
proxy = null; // the vs-2017 wcf client auto generation code no longer implements IDisposable so we remove the object and its references from memory manually
GC.Collect(); // do not allow this to be called as part of an inner loop in production.
return response;
}
private ServiceRequest BuildSanctionsServiceRequest(string nameQuery, bool isSandbox = false)
{
var request = new ServiceRequest();
// Set the name of the bundle we are calling. In this case
request.BundleData = new BundleData
{
BundleName = "DEMO_KYC_SIS"
};
// Build up the query data. For SIS only name query is required.
// This will vary for other services
request.QueryData = new QueryData
{
NameQuery = nameQuery
};
// The service authorization is the same for all services.
// You can also fill in the optional client reference.
request.ServiceAuthorisation = new ServiceAuthorisation
{
APIKey = "{YOU API KEY GOES HERE}",
ClientReference = "{AN OPTIONAL REFERENCE FIELD GOES HERE}"
};
// To call the sandbox version of any service you will need to add the
// query option like this. And call the service using the sandbox query data
// that you can find in our documentation.
if (isSandbox)
{
request.QueryOptions = new Dictionary<string, string> { { "Sandbox", "True" } };
}
return request;
}
}
}Build the solution (Ctrl+Shift+B, or right click on the solution and click on build) to make sure everything is working correctly.
3) The Console App
Now we need to update our main method inside of program.cs to call the new W2Client we’ve created.
3.1 Open up the Program.cs file and replace the contents with the following:
namespace W2GlobalDataDemo2017
{
using System;
public class Program
{
static void Main(string[] args)
{
// Get the name to search for from the console
string nameQuery = string.Empty;
while (string.IsNullOrEmpty(nameQuery))
{
Console.WriteLine("Please enter the name you want to search for:");
nameQuery = Console.ReadLine();
}
// Create a new client
var client = new W2Client();
try
{
// Call the service
var sanctionsCheck = client.SanctionsCheck(nameQuery, false);
sanctionsCheck.Wait();
var result = sanctionsCheck.Result;
if (result != null)
{
// Here we break down the service response into it's components
Console.WriteLine("Service Response:");
Console.WriteLine("-------------------------------------------------");
// 1. Client Data - this simply reflects back the submitted client data
var clientData = result.ClientProvidedData;
Console.WriteLine("Client Reference: {0}", clientData.ClientReference);
Console.WriteLine("-------------------------------------------------");
// 2. Interpret Result - the API returns an interpret result
// which combines the interpretation
// for all the service in the call.
Console.WriteLine("Interpret Result",
result.ProcessRequestResult.TransactionInformation.InterpretResult);
Console.WriteLine("Unique Call Reference",
result.ProcessRequestResult.TransactionInformation.ServiceCallReference);
// 3. Service Transaction Information - this collection contains
// meta information about every service call
// in this example we are only calling one service
// so we are just looking at the first one but for
// more complicated bundles there will be one of these for each service.
var serviceTransactions
= result.ProcessRequestResult.TransactionInformation.ServiceTransactions;
// The next object contains the interpretation of the service call
// and is important to examine it thoroughly
// The name of the service
Console.WriteLine("Service Name: {0}",
serviceTransactions[0].Service);
// Whether the transaction was succesful
Console.WriteLine("Service Transaction Result: {0}",
serviceTransactions[0].ServiceTransactionResult);
// The interpretation of the service i.e. PASS, FAIL etc..
Console.WriteLine("Service Interpret Result: {0}",
serviceTransactions[0].ServiceInterpretResult);
// Any messages the service returns (mostly used for error messages)
Console.WriteLine("Message: {0}",
serviceTransactions[0].ServiceTransactionResultMessage);
// Each service will validate the supplied query data
// and show the results of that validation here:
Console.WriteLine("Validation Details: {0}",
serviceTransactions[0].ServiceValidationDetails);
Console.WriteLine("Validation Result: {0}",
serviceTransactions[0].ValidationResult);
// 4. The service result - This object is different for every
// service and contains the "raw" response for the
// service and is useful to look at for more information about the service result.
// In this example we are just looking at the SIS response
var sisResult = result.ProcessRequestResult.ServiceResult.SISPlusCheckResult;
if (sisResult != null && sisResult.MatchResults != null)
{
Console.WriteLine("Found {0} results for: {1}",
sisResult.MatchResults.Length,
nameQuery);
// Each match will contain the following information
foreach (var match in sisResult.MatchResults)
{
Console.WriteLine("-------------------------------------------------");
Console.WriteLine("DOB: {0}-{1}-{2}",
match.BirthDay, match.BirthMonth, match.BirthYear);
Console.WriteLine("Date of birth match score: {0}",
match.DateOfBirthMatchScore);
Console.WriteLine("Match type: {0}", match.MatchType);
Console.WriteLine("Name: {0}", match.Name);
Console.WriteLine("Name match score: {0}", match.NameMatchScore);
Console.WriteLine("ProfileId {0}", match.ProfileId);
Console.WriteLine("Match type {0}", match.MatchType);
}
}
else
{
Console.WriteLine("Nothing found in SIS search");
}
Console.WriteLine("-------------------------------------------------");
Console.WriteLine("\nPress any key to exit");
Console.ReadKey();
}
else
{
throw new Exception("No response from the service");
}
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
Console.ReadLine();
}
}
}
}
Step Four: Run the program
4.1. Press F5 to run the program. You will be asked to enter a name. Try “Robert Mugabe” and you should see several results. The code samples explain what the elements of the response do.
4.2. Try running the program again with a few different names and see what happens.