ASP.NET

Sample Chapter: Early Adopter Hailstorm (.NET My Services)

Microsoft's .NET My Services is a family of XML web services that improves operational functionality of .NET applications and web pages. In this article Tim takes a look at a sample chapter from Wrox's "Early Adopter Hailstorm (.NET My Services)" book. The chapter talks about what exactly .NET My Services are and how they are composed amongst other things.

As you might expect, the format for a HailStorm response message doesn't differ greatly from that of a request. Of course, this time we need to know its construction in order to parse it rather than build it.

The namespace declarations for the response are the same as those for the request.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:srp="http://schemas.xmlsoap.org/srp"

xmlns:m="http://schemas.microsoft.com/hs/2001/10/myContacts"

xmlns:hs="http://schemas.microsoft.com/hs/2001/10/core"

xmlns:ss="http://schemas.xmlsoap.org/soap/security/2000-12">

<s:Header>

<srp:path>

<srp:action>

http://schemas.microsoft.com/hs/2001/10/core#response</srp:action>

The path element however contains significantly less then before and the <relatesTo> element now contains the UUID for the request message to which this is the response.

<srp:id>uuid:764CBFB8-AA00-46D0-BAEC-3D11F9AA44A8</srp:id>

<srp:relatesTo>

uuid:764CBFB8-A9FF-46D0-BAEC-3D11F9AA44A8</srp:relatesTo>

</srp:path>

As we noted earlier, the licenses element in the response also includes the authorizedRole element that we can include with subsequent messages - in this session only. Using this means that HailStorm doesn't need to re-evaluate the user's role and permissions before executing the request.

<ss:licenses>

<hs:identity>

<hs:kerberos>0123456789ABCDEF</hs:kerberos>

</hs:identity>

<hs:authorizedRole>6jS527ww</hs:authorizedRole>

</ss:licenses>

The <response> header returns the role assigned by HailStorm to the entity associated to the PUID given in the request header. Even if it can't do this for some reason, the response header will always be present in the message. In this case, "rt0" indicates that the client has full read-write access to myContacts. We'll take a more detailed look at roles in Chapter 5.

<h:response role="rt0"/>

</s:Header>

Last but not least, the body of the request message contains either a success message or a SOAP fault. If it's a success, the body may also contain:

The results of the query, if one was made

The reference IDs for any new information added to the safe-deposit box, if any was added

<s:Body>

<h:replaceResponse status="success"/>

</s:Body>

</s:Envelope>

Interpreting SOAPFaults

Of course, it's unlikely that we won't create a few errors here and there, so it's useful to know what to look for when HailStorm returns a fault. SOAPFaults can look quite messy, especially if the lines wrap around to the next line. On reflection though, they can be quite easy to interpret. Like SOAP envelopes, there are two parts to a SOAP Fault:

The overview, comprising the <faultcode> and <faultstring> elements

The details of the errors generated, found in the <faultChain> element

Let's take an example. This is the error returned from the query above if we misspell myContacts, which is case-sensitive, with a lower case 'c'.

<s:Fault>

<s:faultcode>Client</s:faultcode>

<s:faultstring>Syntax error</s:faultstring>

<faultcode> can return one of four values: Client and Server indicate that the client malformed the SOAP message or that the server was unable to process the message internally. The other two, VersionMismatch and MustUnderstand are SOAP-specific. The former indicates that HailStorm found the SOAP enveloper defined by an invalid namespace and the latter that HailStorm failed to fully understand the semantics of a message for which the SOAP mustUnderstand attribute was set.

The <faultstring> element meanwhile holds a short description of the error.

<hs:detail>

<hs:faultResponseAction>Correct</hs:faultResponseAction>

<hs:faultChain>

<hs:fault>

<hs:code>0x70004</hs:code>

<hs:shortDescription>

Syntax error

</hs:shortDescription>

<hs:longDescription>

Undefined name 'mycontacts'.

</hs:longDescription>

</hs:fault>

</hs:faultChain>

</hs:detail>

</s:Fault>

The most useful information is found inside the <faultChain> element, with a long and short description of each error. Sure enough, in the <longDescription> field, informs us that we have spelt the service name incorrectly.

This example is perhaps a bit too simple, generating as it does only one error. As we all know, one error often leads to another and another. The key is just to read what's in front of you. Misspelling a closing tag for example throws three errors back at you, the misspelling first and then two consequences of that.

<s:Fault>

<hs:faultcode>Client</hs:faultcode>

<hs:faultstring>

The end tag found or its namespace does not match the last open tag

</hs:faultstring>

<hs:detail>

<hs:faultResponseAction>Correct</hs:faultResponseAction>

<hs:faultChain>

<hs:fault>

<hs:code>0x20006</hs:code>

<hs:shortDescription>

The end tag found or its namespace does not match the last open

tag</hs:shortDescription>

<hs:longDescription>

Tag name does not match queryRequest :

Tag name mismatch on end tag Line: 4 Column: 17

</hs:longDescription>

</hs:fault>

<hs:fault>

<hs:code>0x20006</hs:code>

<hs:shortDescription>

The end tag found or its namespace does not match the last open

tag </hs:shortDescription>

<hs:longDescription>

XmlEndElement call returned an error code Line: 4 Column: 17

</hs:longDescription>

</hs:fault>

<hs:fault>

<hs:code>0x20006</hs:code>

<hs:shortDescription>

The end tag found or its namespace does not match the last open

tag </hs:shortDescription>

<hs:longDescription>

Error parsing the body of the request

</hs:longDescription>

</hs:fault>

</hs:faultChain>

</hs:detail>

</s:Fault>

Of course, there's only one mistake rather than three. I think it could be because 'The end tag found or its namespace does not match the last open tag'. Hmm.

It's never going to be as trivial as this all the time, but you should at least know now how to read a SOAP fault if that's all you have to go by. On the other hand, if you're using an XML IDE, or perhaps even the HailStorm extension for Visual Studio .NET that is in the works, the raw SOAP fault message will probably be parsed for you first - lucky you.