Read an Excerpt
Chapter 2 Understanding the .NET Data Manipulation Language and XMIMicrosoft .NET My Services is a data service and as such provides access to user data as well as services surrounding that data, collectively known as the service fabric. In addition to providing XML-based access to your data, .NET My Services provides facilities for protecting and securing your information and for authenticating individuals and applications that want to gain access to your data. Beyond these features, the service fabric allows you to tailor how your .NET My Services messages are transported, by allowing for the creation of synchronization points. The service fabric also provides an infrastructure for you, as a developer, to extend your Web offerings to your users.
Included in the service fabric are the fundamental application programming interface (API) and transport features. To use .NET My Services, you have to speak XML and do so with SOAP. Fortunately, SOAP and XML are available just about everywhere. Although .NET My Services might use SOAP as a protocol, and .NET My Services might allow for Web service connectivity via WSDL and object proxies in Microsoft Visual Studio .NET, all .NET My Services interaction comes down to some simple XML commands. These commands, known as HSDL, drive interaction with the Web services. HSDL allows for queries, updates, inserts, and other actions as well as allowing their payloads to interact with .NET My Services services. HSDL is itself carried inside a SOAP envelope. In this chapter, we will examine .NET My Services's XML data manipulation language called HSDL, and we will look at the exposed features of the different XML-based service documents known as the XML Message Interface (XMI).
HSDL and XMI make up a large portion of a developer's interaction with .NET My Services. The XMI is a series of exposed XML-based interfaces that support service interaction for .NET My Services. HSDL is the name for the XML elements used while interacting with the service.
HSDL BasicsHSDL is the command interface for .NET My Services. Six core commands are used in the course of interaction with the various services, along with specific methods designed for common tasks in particular services. HSDL is primarily focused on transporting data in and out of .NET My Services service documents, but its design and syntax reflect two other underpinnings of .NET My Services: security and data structure.
SecurityEach .NET My Services service supports the six primary commands but allows fine-tuning of the commands depending on who is gaining access to the service on your behalf. For example, you might want an airline to have access to your calendar but not to your list of contacts. Each service contains a wealth of attributes that you can use to tailor the visibility and privacy of your .NET My Services data. .NET My Services will enforce a role map against both users and applications that attempt to gain access to this data.
Security is a part of every .NET My Services request. From the SOAP headers that include Kerberos information to the service's inspection of the packet and enforcement of roles and ACLs, security plays a big part in how a service operates. In this chapter, however, we focus primarily on the nature of an HSDL message and not so much on its security information.
Service StructureApart from security, each .NET My Services service is made up of key XML nodes that hold more relevance than others. HSDL has established two main types of nodes. The first type is referred to as blue in the XMI Manual (included with the .NET My Services SDK) and represents primary data elements of any given .NET My Services service. Every immediate child of any service root element (such as <myProfiles> or <myContacts>) is a blue, or primary, element. The second type of XML node that HSDL is concerned with reflects .NET My Services's extensive utilization of XPath in HSDL. XPath is a part of every HSDL command because XPath is used to target a specific element or portion of a service document. XPath uses the concept of a predicate to DEFINITION. In HSDL, red nodes represent attributes and elements that you can use as part of an XPath predicate when selecting nodes in HSDL. In other words, consider the following service document fragment:
<myContacts> <contact id="some_guid">
Both myContacts and the contact element are blue types, as they are primary elements in the service definition. The id attribute is defined as a red element within the service, which opens the door for its use in an XPath statement as a predicate:
The above XPath would select a specific contact element that contained a child id attribute with the value of some_guid.
In addition to these primary and secondary (blue and red) elements, some sections of service data cannot be directly manipulated with HSDL. For example:
<contact> <name> <firstName>Christopher</firstName> <middleName>A.</middleName> <lastName>Jones</lastName> </name> </contact>
In the above contact entry within the .NET contacts service, you could not write an HSDL statement that attempts to select (again, via XPath syntax) /contact/name[middleName="A."]. The service would not let you predicate against this generic element of the service document because it is neither the blue nor red type. As we dive into some specific HSDL commands, you will better understand the role that XPath plays.
HSDL CommandsRegardless of security or roles, .NET My Services offers six fundamental commands to interact with the various .NET My Services service documents.
The insert command allows a .NET My Services client to insert a new primary element (blue) into the user's service document or to insert a secondary element or attribute (red) into a primary (blue) element. The SOAP response of an insert request indicates the node count of the request's select attribute, as well as the unique, .NET My Services-created IDs for each of the new nodes created.
The update command allows a client to combine a series of insert, delete, and replace requests into one bulk request. This allows the combination of actions to be treated as a single atomic command in terms of success or failure.
The query request command allows for basic data retrieval functionality. As with all the others, an XPath statement rides in a select attribute telling .NET My Services which XML nodes within the service document you wish to see.
The replace message command allows the client to target a specific primary element within the service document and replace its contents with the contents supplied in the current replace request. The targeted element is replaced in its entirety.
The delete request command is a simple element with a select attribute indicating (again with XPath) the targeted element to delete from the service document.
The subscriptionResponse command is used to request a subscription to certain .NET My Services information and be notified when that information has changed.
XPath and HSDLXPath plays a major role in the six .NET My Services commands discussed earlier. Since all .NET My Services data is maintained in XML, it is critical to understand exactly how you target specific information both for retrieval and for manipulation. All HSDL commands utilize a select attribute at some point in their structure. This select attribute targets an XML node or nodeset within the document. For example, consider the following document:
<myContacts> <contact visibility="public" changeNumber="1" id="7c77a388-934a-11d5-a972-00b0d0f1dea5"> <name changeNumber="1" id="7c77a389-934a-11d5-a972-00b0d0f1dea5"> <title>Mr.</title> <firstName>Christopher</firstName> <lastName>Jones</lastName> </name> <notes/> <emailAddress id="7c77a38a-934a-11d5-a972-00b0d0f1dea5" changeNumber="1"> <address>email@example.com</address> </emailAddress> <emailAddress id="9f6cb21d-934a-11d5-a972-00b0d0f1dea5" changeNumber="1"> <address>firstname.lastname@example.org</address> </emailAddress> <workInformation id="7c77a38b-934a-11d5-a972-00b0d0f1dea5" changeNumber="1"> <profession>Maybe</profession> <company> <name>Microsoft</name> </company> <jobTitle>Programmer/Writer</jobTitle> </workInformation> </contact> </myContacts>
In this document, a single contact element contains information about an individual contact. If you wanted to retrieve this contact and all other contact elements within the service document, your HSDL insert request would appear as:
This query request contains an XPath query (xpQuery) that selects all contact elements beneath the root node in standard XPath syntax (the // is XPath for select all). The response to this message would be a collection of contact elements and all of their content.
If you just wanted to select the e-mail addresses of this contact (or all of your contacts), you could tailor your query differently:
<queryRequest> <xpQuery select="//emailAddress"/> </queryRequest>
This example selects all emailAddress elements within the service document. The response would be all of the emailAddress elements. The earlier document contains a contact with multiple e-mail addresses. Performing the preceding queryRequest against it would generate a response looking something like this:
<queryResponse> <xpQueryResponse status="success"> <emailAddress id="7c77a38a-934a-11d5-a972-00b0d0f1dea5" changeNumber="1"> <address>email@example.com</address> </emailAddress> <emailAddress id="9f6cb21d-934a-11d5-a972-00b0d0f1dea5" changeNumber="1"> <address>firstname.lastname@example.org</address> </emailAddress> </xpQueryResponse> </queryResponse>
You can use XPath predicates against secondary (red) elements and attributes to further tailor your queries. For example, if you wanted a contact with a specific name element, in this case containing a specific first name such as Christopher, you could use a predicate to pull the right contact element for you:
<queryRequest> <xpQuery select="/myContacts/contact[name/firstName='Christopher']"/> </queryRequest>
The XPath selects a contact element but only a contact element with a child name element that contains a firstName element with the text "Christopher...."