Project Description
POX.NET is a set of utility classes that assist in creating POX (Plain Old Xml) services and clients in .NET 2.0. This libary leverages classes within .NET 2.0 and does not require any additional add-ons. With POX.NET working with POX in .NET is a breeze.

For background of this project see the original blog post at http://blogs.msdn.com/gblock/archive/2007/01/22/pox-xmlhttp-in-net-2-0.aspx.

Sample POX Client / Service and test fixture are included in the source.

Mini QuickStart - Using POX.NET

POX.NET allows you to do two main things. 1. Create a POX client to invoke a POX service. 2. Create an ASP.NET POX service.

Invoking a POX service.

In order to invoke a POX Service using POX.NET you do 3 things:
  1. Create a POXClient instance
  2. Invoke the Post<T> method passing an Xml serializable object instance.
  3. Call GetResponse<T> and retrieve the response type.

The example below shows how to Invoke a POX service that accepts an Order object as part of the request, and retrieves an OrderResponse object as part of the response.

using Microsoft.POXUtils

public OrderResponse SubmitOrder(Order order)
{
    Order Order = new Order(1234);
    POXClient Client = new POXClient("http://Orders/SubmitOrder.aspx");
    Client.Post(order);
    return Client.GetResponse<OrderResponse>();
} 


Creating a POX Service

To create a POX service, follow the following steps:
  1. Add a new ASPX page in your web application which represents you service i.e. OrderService.aspx.
  2. Change the base class to inherit from POXPage.
  3. In the Page_Load event handler, call the GetRequest<T> method to retrieve the request object that the service has been passed as part of the invocation.
  4. Create your response object and call the WriteResponse<T> method.

The example shows how to create a POX service that receives the Order object posted in the client example, and returns an OrderResponse.

using Microsoft.POXUtils

class OrderService : POXPage {

    protected void Page_Load(object sender, EventArgs e)
    {
        Order CurrentOrder = GetRequest<Order>();
        if (CurrentOrder != null)
        {
            OrderResponse OrderResponse = new OrderResponse(CurrentOrder, "confirmed", "1000");
            WriteResponse(OrderResponse);
        }
    }
} 


What's included in the package?

Microsoft.POXUtils

Microsoft.POXUtils.Client

Provides a class which enscapsualtes a POX service invocation. The class exposes methods for posting and retreving Xml Serializable objects, streams and Xml Documents via a POX Service.
  • public void Post<T>(T objectToPost) - Serializes objectToPost and then posts the stream to a POX service.
  • public void PostDocument(XmlDocument document) - Posts the contents of an document to a POX service.
  • public void PostStream(stream documentStream) - Posts a stream to a POX service.
  • public T GetResponse<T>() - Retrieves the result stream from a POX service an deserializes to an instance of type T.
  • public XmlDocument GetResponseDocument() - Retrives the result stream from a POX service returns an XmlDocument loaded with that stream.
  • public MemoryStream GetResponseStream() - Retrieves the result stream from a POX service and loads it into a MemoryStream.
  • public XmlWriterSettings WriterSettings - Allows ovewriting the settings for the internal XmlSerializer to use when posting an object or an XmlDocument.
  • public XmlReaderSettings ReaderSettings - Allows overwriting the settings for the internal XmlSerializer to use when deserializing an object or retrieving an XmlDocument.

Microsoft.POXUtils.POXPage

Provides an inherited System.Web.UI.Page class that exposes methods for handling a POX web request and response.
  • public T GetRequest<T>() - Retrieves the request stream and deserializes to an instance of type T.
  • public XmlDocument GetRequestDocument() - Retrieves the request stream and returns an XmlDocument loaded with that stream.
  • public void WriteResponse<T>(T objectToWrite) - Serializes objectToWrite and then posts the stream to the response.
  • public void WriteResponseDocument(XmlDocument document) - Posts the contents of document to the response.
  • public XmlWriterSettings WriterSettings - Allows ovewriting the settings for the internal XmlSerializer to use when posting an object or an XmlDocument to the response.
  • public XmlReaderSettings ReaderSettings - Allows overwriting the settings for the internal XmlSerializer to use when deserializing an object or retrieving an XmlDocument from the request.

Microsoft.POXUtils.Common

Handles low-level streaming, serialization and deserialization for Client and POXPage.
  • internal static void WriteStream(Stream inputStream, Stream outputStream, int length) - Copies the contents of inputStream to outputStream.
  • private static void WriteStream(Stream outputStream, byte[] streamBuffer,int length) - Copies the contents of streamBuffer to outputStream.
  • internal static MemoryStream ReadStream(Stream inputStream, int length) - Reads the contents of inputStream and returns a new MemoryStream.
  • internal static MemoryStream SerializeObject<T>(T objectToSerialize, XmlWriterSettings writerSettings) - Serializes objectToSerialize to a MemoryStream using the provided settings.
  • internal static T DeserializeObject<T>(Stream inputStream, XmlReaderSettings readerSettings) - Deserializes inputStream to an instance of type T using the provided settings.
  • internal static XmlDocument GetDocumentFromStream(Stream stream, XmlReaderSettings readerSettings) - Loads the contents of stream into an XmlDocument using the provided settings.
  • internal static MemoryStream GetStreamFromDocument(XmlDocument document, XmlWriterSettings writerSettings) - Writes the contents of document to a stream using the provided settings.

Releases

.1 Alpha - http://www.codeplex.com/POXNET/Release/ProjectReleases.aspx?ReleaseId=2183
.11 Alpha - http://www.codeplex.com/POXNET/Release/ProjectReleases.aspx?ReleaseId=2966


Last edited Apr 9, 2007 at 7:23 AM by gblock, version 11