Submit to Reddit      
  

The ChannelAdam SOAP Library

Overview

The ChannelAdam SOAP Library is an open source (Apache License 2.0) .NET code library that provides a fluent API to make it as easy as possible to create a SOAP 1.1 or SOAP 1.2 message.

Among other things, it is perfect for building SOAP envelopes to use in lightweight web frameworks such as Nancy.


Getting Started

NuGet Package Installation

To install the ChannelAdam.Soap NuGet package run the following command in the Package Manager Console:

PM> Install-Package ChannelAdam.Soap


Show Me Some Code!

Below are some simple examples. There are plenty of overloads and other methods for more advanced usage - see the reference in the next section.

SOAP Envelope with a Header Action and Body

Here is a simple example of creating a SOAP 1.1 envelope with a header action and body payload.

string envelopeXml = SoapBuilder.CreateSoap11Envelope()
    .WithHeader.AddAction("http://my.action/here")
    .WithBody.AddEntry("<myXml>hello from the body</myXml>")
    .Build()
    .ToString();

And for SOAP 1.2:

string envelopeXml = SoapBuilder.CreateSoap12Envelope()
    .WithHeader.AddAction("http://my.action/here")
    .WithBody.AddEntry("<myXml>hello from the body</myXml>")
    .Build()
    .ToString();

There is even an overload to create the body entry from .NET objects. For instance:

public class MyModel
{
    public string Value { get; set; } 
}

...

var model = new MyModel { Value = "hello!" };

string envelopeXml = SoapBuilder.CreateSoap12Envelope()
    .WithHeader.AddAction("http://my.action/here")
    .WithBody.AddEntry(model)
    .Build()
    .ToString();

Easy!

SOAP Faults

To create a SOAP 1.1 fault:

string envelopeXml = SoapBuilder.CreateSoap11Envelope()
    .WithBody.SetFault(Soap11FaultCode.Client, "SOAP 1.1 fault string here")
    .Build()
    .ToString();

And for a SOAP 1.2 fault:

string envelopeXml = SoapBuilder.CreateSoap11Envelope()
    .WithBody.SetFault(Soap12FaultCode.Sender, "SOAP 1.2 fault reason here")
    .Build()
    .ToString();

There are overloads to set other SOAP fault value properties as well.


Reference

This reference assumes that the reader is familiar with SOAP terminology. For more information see the following SOAP specifications:


SoapBuilder

The SoapBuilder static class is the fluent starting point for building a SOAP 1.1 or SOAP 1.2 envelope.

The SoapBuilder static class has two methods:

  • ISoap11EnvelopeBuilder CreateSoap11Envelope() - to start the process of creating a SOAP 1.1 envelope

  • ISoap12EnvelopeBuilder CreateSoap12Envelope() - to start the process of creating a SOAP 1.2 envelope

The ISoap11EnvelopeBuilder interface has two properties and one method:

  • ISoap11BodyBuilder WithBody { get; } - to specify the SOAP body or a fault

  • ISoap11HeaderBuilder WithHeader { get; } - to specify the SOAP header

  • XContainer Build() - to finally build the SOAP envelope as specified

The ISoap12EnvelopeBuilder interface is similar:

  • ISoap12BodyBuilder WithBody { get; }

  • ISoap12HeaderBuilder WithHeader { get; }

  • XContainer Build()

Usage

The general procedure for usage is:

  1. Call one of the SoapBuilder.CreateSoap??Envelope() methods.

  2. If necessary, add a header via the WithHeader property.

  3. Add a body or fault message via the WithBody property.

  4. Once all the details have been specified, simply call the Build() method which will return an XContainer.

  5. If there is something that you need to do to the contents of the SOAP envelope that is not currently allowed by the API, then you can always directly modify the elements in the XContainer and do magical things with LINQ.

  6. A simple .ToString() on the XContainer returned from Build() will then give you the XML string of the SOAP envelope/payload - by default formatted with indentation. There is also the overload .ToString(System.Xml.Linq.SaveOptions options) that allows you to change the formatting of whitespace and indentation.


Specify the SOAP Header

The SOAP header can be specified via the WithHeader property.

For SOAP 1.1, WithHeader chains the following methods:

ISoap11EnvelopeBuilder AddAction(string action);

ISoap11EnvelopeBuilder AddBlock(string headerXml);
ISoap11EnvelopeBuilder AddBlock(XContainer headerBlock);
ISoap11EnvelopeBuilder AddBlock(object toSerialise);
ISoap11EnvelopeBuilder AddBlock(object toSerialise, string toElementName, string toElementNamespace);

ISoap11EnvelopeBuilder SetStandardSoapEncoding();
ISoap11EnvelopeBuilder SetCustomSoapEncoding(string soapEncodingNamespace);

Notes:

  • AddAction(string action) adds an action header block with the specified action.
  • AddBlock(XContainer headerBlock) adds any arbitrary header block - e.g. from a System.Xml.Linq.XElement.
  • AddBlock(object toSerialise, string toElementName, string toElementNamespace) serialises the given object and during serialisation overrides the XML element name and namespace with those specified.
  • ISoap11EnvelopeBuilder SetStandardSoapEncoding() sets the SoapEncoding attribute to the standard encoding namespace
  • ISoap11EnvelopeBuilder SetCustomSoapEncoding(string soapEncodingNamespace) sets the SoapEncoding attribute to your custom namespace

For SOAP 1.2, WithHeader is nearly identical to SOAP 1.1, except an ISoap12EnvelopeBuilder is returned instead of a ISoap11EnvelopeBuilder.


Specify the SOAP Body Payload or Fault

The SOAP body payload or fault can be specified via the WithBody property which provides the following methods.

For SOAP 1.1:

ISoap11EnvelopeBuilder AddEntry(string bodyXml);
ISoap11EnvelopeBuilder AddEntry(XContainer fromNode);
ISoap11EnvelopeBuilder AddEntry(object toSerialise);
ISoap11EnvelopeBuilder AddEntry(object toSerialise, string toElementName, string toElementNamespace);

ISoap11EnvelopeBuilder SetFault(Soap11FaultCode code, string faultString);
ISoap11EnvelopeBuilder SetFault(Soap11FaultCode code, string faultString, string faultActor);
ISoap11EnvelopeBuilder SetFault(Soap11FaultCode code, string faultString, string faultActor, IEnumerable<XContainer> detailEntries);

ISoap11EnvelopeBuilder SetStandardSoapEncoding();
ISoap11EnvelopeBuilder SetCustomSoapEncoding(string soapEncodingNamespace);

Notes:

  • AddEntry(object toSerialise, string toElementName, string toElementNamespace) serialises the given object and during serialisation overrides the XML element name and namespace with those specified.


SOAP 1.2 Faults are more descriptive than SOAP 1.1, hence the overloads of SetFault with more parameters.

For SOAP 1.2:

ISoap12EnvelopeBuilder AddEntry(string bodyXml);
ISoap12EnvelopeBuilder AddEntry(XContainer fromNode);
ISoap12EnvelopeBuilder AddEntry(object toSerialise);
ISoap12EnvelopeBuilder AddEntry(object toSerialise, string toElementName, string toElementNamespace);

ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, string reason);
ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, string subCode, string reason);
ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, XNamespace subCodeNamespace, string subCode, string reason);
ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, XNamespace subCodeNamespace, string subCode, string reason, string reasonXmlLanguage);
ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, XNamespace subCodeNamespace, string subCode, string reason, string reasonXmlLanguage, string node);
ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, XNamespace subCodeNamespace, string subCode, string reason, string reasonXmlLanguage, string node, string role);
ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, XNamespace subCodeNamespace, string subCode, string reason, IEnumerable<XContainer> detailEntries);
ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, XNamespace subCodeNamespace, string subCode, string reason, string reasonXmlLanguage, IEnumerable<XContainer> detailEntries);
ISoap12EnvelopeBuilder SetFault(Soap12FaultCode code, XNamespace subCodeNamespace, string subCode, string reason, string reasonXmlLanguage, string node, string role, IEnumerable<XContainer> detailEntries);

ISoap12EnvelopeBuilder SetStandardSoapEncoding();
ISoap12EnvelopeBuilder SetCustomSoapEncoding(string soapEncodingNamespace);




comments powered by Disqus