wcfps

WcfPS is a PowerShell module to consume SOAP endpoints.

The module provides the cmdlets that mimic how various IDEs e.g. Visual Studio build the proxies for soap endpoints. All IDEs do pretty much the following:

1. Find the metadata endpoint. This is either through the ?wsdl format or by consuming a metadata exchange endpoint.
2. Download the metadata.
3. Generate specific to the programming language assets.

For convenience, in the rest of the post I’ll use Visual Studio as a reference environment.

If you have already worked with C# and WCF then you have already noticed the generated C# code under ServiceReferences folder as well as the System.ServiceModel configuration in the app.config or web.config files. When you execute the program, all the information is already there and the program consumes directly the target endpoints. You can of coarse program the bindings etc but most probably you will still use the generated proxy classes.

But in the PowerShell environment that is not possible. The PowerShell console is a multipurpose executable. You can always hack your way around this but that is not the purpose and not the purpose of this post. In PowerShell you need to always generate the proxies and their binding configuration before actually consuming the endpoints. This is what WcfPS offers through its cmdlets:

• New-WcfWsdlImporter is the starting point. It will download the metadata and create an importer object to help with the rest of the flow.
• New-WcfProxyType uses the importer to generate the proxy classes. This is the equivalent of the generated files under the Service References folder in Visual Studio. There is an option to save the proxies into an assembly for future use.
• New-WcfServiceEndpoint uses the importer to generate the binding, contract and endpoint configuration. This is the equivalent of the System.ServiceModel configuration added in your app.config or web.config files
• Set-WcfBindingConfiguration controls some common binding options such as timeout and quota.
• New-WcfChannel combines the service endpoint and proxy type to create a channel to the the target endpoint.

Here is an example code for $svcEndpoint

$importer=New-WcfWsdlImporter -Endpoint $svcEndpoint -HttpGet
$proxyType=$importer | New-WcfProxyType
$endpoint=$importer | New-WcfServiceEndpoint -Endpoint $svcEndpoint
$channel=New-WcfChannel -Endpoint $endpoint -ProxyType $proxyType -Credential $credential

At this point the $channel is created and you can benefit from PowerShell auto-complete functionality to consume the methods.

WcfPS against WS Trust

With SDL Knowledge Center we use federated services to protect the WCF endpoints. In context of SOAP and WS*, this usually means a Security Token Service that provides WS Trust endpoints. WS Trust is still SOAP, therefore it provides metadata and can be consumed by WCF clients.
For example if the metadata exchange endpoint for the STS is $mexUri then to this script creates a proxy

$issuerImporter=New-WcfWsdlImporter -Endpoint $mexUri
$proxyType=$issuerImporter | New-WcfProxyType
$issuerEndpoint=$issuerImporter | New-WcfServiceEndpoint
$channel=New-WcfChannel -Endpoint $issuerEndpoint -ProxyType $proxyType -Credential $credential

WcfPS provides an extra cmdlet to wrap this functionality. New-SecurityToken does behind the scenes the above and makes a request to issue a token. This is fairly complicated and that is why I created this extra cmdlet. Here is an example to issue a symmetric token from $issuerEndpoint for identifier $appliesTo

New-SecurityToken -Endpoint $issuerEndpoint -Credential $Credential -AppliesTo $appliesTo -Symmetric

Remarks

The WcfPS was developed against SDL Knowledge Center API. I’ve worked with WCF since 2007 but since 2011 my focus has been on SOAP endpoints with federated authentication. I’m confident that the cmdlets will work on any SOAP endpoint but I cannot test them right at this point. If you like the idea or if you have to work with WCF then please contribute on github.

At this moment in time the cmdlets are not documented. They do not support the Get-Help. If you are looking for more examples then please refer to the Pester scripts.

• Test-ISHExternal incrementally builds all necessary assets to execute a what is known as GetVersion from Wcf/API25/Application.svc.
• Test-WSTrust.ps1 incrementally builds all necessary assets to request a Symmetric or Bearer token from the STS.

I currently use this module to do a low level test of the flow required to get a token. I’ll make a new post in the near future about this.