Microsoft® .NET My Services Specification   by Microsoft Corporation

From the Publisher

Get the drilldown on "HailStorm" right from the source! HailStorm is the codename for a set of XML-based Web services delivered by Microsoft as part of the Microsoft .NET initiative. HailStorm makes it easier for developers to extend existing Web services and create new, sustainable Internet business models. This architectural specification is the first book to provide not only an explanation of HailStorm, but also to describe its messaging interface model, security model, and services.

Provides professional developers and Web developers with their first look at "HailStorm" services and the HailStorm messaging interface model and security model


* Comes right from the HailStorm source—the architects of the Microsoft .NET initiative

* Contains brief descriptions of HailStorm, the HailStorm messaging interface model, the HailStorm security model, and a description of each HailStorm service

* Includes two preview chapters from "Introducing Microsoft XML Web Services" by Microsoft Press, plus a CD containing the HailStorm Software Development Kit (SDK)

Product Details

• Table of Contents
• Read an Excerpt
• Read a Sample Chapter

Table of Contents

Read an Excerpt

Chapter 2  Understanding the .NET Data Manipulation Language and XMI

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 Basics

Security

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 Structure

<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:

/myContacts/contact[id='some_guid']

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 Commands

insert

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.

update

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.

query

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.

replace

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.

delete

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.

subscriptionResponse

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 HSDL

<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>chrisaj@microsoft.com</address>
  </emailAddress>
  <emailAddress 
   id="9f6cb21d-934a-11d5-a972-00b0d0f1dea5" changeNumber="1">
   <address>ca_jones23@hotmail.com</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:

<queryRequest><xpQuery select="//contact"/></queryRequest>

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>someone@microsoft.com</address>
  </emailAddress>
  <emailAddress 
   id="9f6cb21d-934a-11d5-a972-00b0d0f1dea5" changeNumber="1">
   <address>ca_jones23@hotmail.com</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...."

Read a Sample Chapter

• HSDL Basics
• Security
• Service Structure
• HSDL Commands
• XPath and HSDL
• Actual HSDL Examples
• An insert Example
• A delete Example
• A replace Example
• HSDL and SOAP
• .NET My Services Service Structure
• The name Element
• The address Element
• The emailAddress Element
• Service Specific Methods
• .NET calendar service
• The XMI Manual

Microsoft .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 Basics

HSDL 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.

Security

Each .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 Structure

Apart 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:

/myContacts/contact[id='some_guid']

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 Commands

Regardless of security or roles, .NET My Services offers six fundamental commands to interact with the various .NET My Services service documents.

insert

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.

update

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.

query

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.

replace

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.

delete

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.

subscriptionResponse

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 HSDL

XPath 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>chrisaj@microsoft.com</address>   </emailAddress>   <emailAddress    id="9f6cb21d-934a-11d5-a972-00b0d0f1dea5" changeNumber="1">    <address>ca_jones23@hotmail.com</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:

<queryRequest><xpQuery select="//contact"/></queryRequest>

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>someone@microsoft.com</address>   </emailAddress>   <emailAddress    id="9f6cb21d-934a-11d5-a972-00b0d0f1dea5" changeNumber="1">    <address>ca_jones23@hotmail.com</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."

Actual HSDL Examples

To really understand HSDL, you have to use it. The last section shows how XPath is used in conjunction with a queryRequest to extract information. In this section, we'll look at some of the other HSDL commands. You can start by populating a service document using the hspost utility provided with the .NET My Services SDK. Within the bin directory of your SDK CD, there are two command line tools: hsprov and hspost. If you read the installation instructions and set up the server, you most likely have provisioned yourself for a particular service. If not, the syntax is quite simple:

C:\> hsprov –l http://yourServer –o username –s myProfile

Of course, you'll need to replace yourServer with the name of your machine running ".NET My Services Services-in-a-Box" and replace username with your log in name.

An insert Example

Once provisioned, you can begin inserting data into the service. To populate your profile with some bare minimum information, you can start with the following document fragment, substituting values for your own:

<myName visibility="public">   <title>Mr.</title>   <firstName>Christopher</firstName>   <middleName>A.</middleName>   <lastName>Jones</lastName> </myName> <picture visibility="public">   <url>http://www.zeropath.com</url> </picture>

To deliver this payload and insert it, you'll need to wrap it with a proper HSDL insertRequest command and select the appropriate place within the service document to insert the new content:

<insertRequest select="/myProfile">  <myName visibility="public">   <title>Mr.</title>   <firstName>Christopher</firstName>   <middleName>A.</middleName>   <lastName>Jones</lastName>  </myName>  <picture visibility="public">   <url>http://www.zeropath.com</url>  </picture> </insertRequest>

At this point, you can use hspost.exe to submit the data to .NET My Services and gauge the success of your action by the response that is returned. When you run hspost.exe, it will return the complete SOAP envelope returned by .NET My Services to you.

G:\bin\sdk\bin>hspost -d content -s myProfile -f insertProfEx.xml <?xml version='1.0'?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:h="http://schemas.microsoft.com/hs/2001/10/core"> <s:Header> <m:path xmlns:m="http://schemas.xmlsoap.org/srp" s:mustUnderstand="1" s:actor="http://schemas.xmlsoap.org/soap/actor/next"> <m:action>http://schemas.microsoft.com/hs/2001/10/core#response</m:action> <m:from>http://ozmatron</m:from> <m:rev></m:rev> <m:id>29e9cad4-9368-11d5-a972-00b0d0f1dea5</m:id> <m:relatesTo>29dac581-9368-11d5-a2d1-00b0d0e9071d</m:relatesTo> </m:path> <h:response s:mustUnderstand="1"></h:response> </s:Header> <s:Body> <responseBody> <insertResponse status="success" selectedNodeCount="1" newChangeNumber="450"> <newBlueId id="29e9cad2-9368-11d5-a972-00b0d0f1dea5"/> <newBlueId id="29e9cad3-9368-11d5-a972-00b0d0f1dea5"/> </insertResponse> </responseBody> </s:Body> </s:Envelope>

The .NET My Services response shows the new primary elements that were created, specifically your myName element and your picture element. They have been given IDs and change numbers as well. Both items play an important role in synchronizing and caching. The IDs also give you the ability to insert duplicate elements into the service document. When a seemingly identical contact element is placed within myContacts, for example, perhaps content within a descendent element is different, it is given a unique ID to ensure that there is no confusion with another element.

A delete Example

The task of deleting a single .NET My Services element or collection of elements requires significantly less XML than inserting data does (for obvious reasons). A single deleteRequest element with an accompanying select attribute is all that is required to delete an XML node within a service document.

To delete a specific element, you would use a specific XPath expression coupled perhaps with an ID predicate:

<deleteRequest select="/myProfile/picture[@id='29e9cad3-9368-11d5-a972-00b0d0f1dea5']"/>

This action would delete the picture element created in the insert example. The ID predicate is retrievable in the response of the insertRequest. The insertRequest response contained newBlueId elements that contained the ID value of the freshly created elements.

To delete your profile in its entirety, you can use a more generic XPath expression that will remove everything below the root node:

<deleteRequest select="/myProfile/*"/>

This deleteRequest would wipe out all the elements appearing beneath myProfile.

A replace Example

Replacing an element is a good choice when you are changing information within the document, such as your e-mail address or name. In the myProfile document I created earlier, I used title, firstName, middleName, and lastName elements. That's a little too formal for me, so I can replace the myName element with abbreviated content:

<replaceRequest  select="/myProfile/myName[@id='63e63000-936e-11d5-a972-00b0d0f1dea5']">   <myName visibility="public">     <firstName>Chris</firstName>     <lastName>Jones</lastName>   </myName> </replaceRequest>

Now the myName element is replaced with one that does not contain a title or middleName element. The replaceRequest XPath expression looks for a myName element with a specific ID. After deleting myProfile earlier and then recreating it, I was able to track the newBlueId used for the myName element. I used that ID here in my XPath to select and replace the correct myName element.

As you can see, many of the HSDL commands work in a similar fashion and they all depend on XPath. The XMI Manual that ships with the .NET My Services SDK provides a comprehensive reference on HSDL syntax.

HSDL and SOAP

In the last section, you used hspost.exe from the .NET My Services SDK to send your HSDL requests to the .NET My Services server. The server responded with a SOAP packet, which hspost.exe dumped to standard output for you to see. In this section, we'll look at the SOAP packet a little more closely.

A .NET My Services SOAP packet is a straightforward envelope that carries the HSDL payload (or response) in the SOAP envelope. .NET My Services makes extensive use of the SOAP header element, placing within it the elements and attributes relevant to security and the current transaction and requesting application. For example, consider the following HSDL queryRequest:

<queryRequest>   <xpQuery select="/myProfile"/> </queryRequest>

The SOAP packet generated by hspost.exe to send this queryRequest illustrated earlier in the chapter appears as the following:

<?xml version='1.0'?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"             xmlns:x="http://schemas.xmlsoap.org/rp"             xmlns:h="http://schemas.microsoft.com/hs/2001/10/core"             xmlns:ss="http://schemas.xmlsoap.org/soap/security/2000-12">   <s:Header>     <x:path>         <x:action>http://schemas.microsoft.com/hs/2001/10/core#request</x:action>        <x:rev><x:via /></x:rev>         <x:to>http://species8472</x:to>         <x:id>34ef9bf1-a942-11d5-bf0e-00b0d0ccc121</x:id>     </x:path>     <ss:licenses>         <h:identity mustUnderstand="1">             <h:kerberos>1</h:kerberos>         </h:identity>     </ss:licenses>     <h:request mustUnderstand="1" service="myServices" document="content" method="query" genResponse="always">         <h:key instance="0" cluster="0" puid="3066" />     </h:request> </s:Header>   <s:Body>        <queryRequest               xmlns:mp = "http://schemas.microsoft.com/hs/2001/10/myProfile"               xmlns:ms = "http://schemas.microsoft.com/hs/2001/10/myServices">               <xpQuery opId="1" select="/ms:myServices/ms:service[@name='myProfile']"/>        </queryRequest> </s:Body> </s:Envelope>

As you can see, the simple HSDL request is wrapped in a significant amount of SOAP. The SOAP header's path element contains information about the forward path of the message and may optionally contain information about the reverse path as well. While it is probably best to think in terms of a client device querying .NET My Services for its user's information, in production deployment, it is likely that any number of Web servers or applications may end up requesting .NET My Services on a user's behalf and may want fine grained control over the message pathway.

The SOAP header also contains an interesting licenses element. As of this writing, .NET My Services is not yet using Kerberos and Passport. The structure of this SOAP header is not likely to change too greatly, but the contents certainly will. This header will include the security information for any given .NET My Services SOAP packet.

The request element within the SOAP header contains several practical pieces of information related directly to the request at hand. The service attribute defines the particular service targeted. The document method indicates whether or not this request is intended for administrative purposes ("admin") or data-related purposes ("content"). The method attribute indicates the type of request being performed—the HSDL command. As of this writing, this corresponds to the first word of the request element. For example, a <queryRequest> requires a method attribute with the value "query". An <insertRequest> requires an "insert" method.

The SOAP body is probably the simplest aspect of a .NET My Services request, as that is where the HSDL resides. In this case, the Body element simply contains the request:

  <s:Body>     <queryRequest>       <xpQuery opId="1"        select="/myServices/service[@name='myProfile']"/>     </queryRequest> </s:Body>

As .NET My Services evolves, different APIs and run time services may help you avoid writing SOAP packets by hand. As of this writing, service integration with Visual Studio .NET is planned, allowing you to treat .NET My Services as any other Web service using Visual Studio, including the use of simple proxy objects. Likewise, a client run time is in development that will help the developer in securing Kerberos information, defining a service end point, and delivering the SOAP packet. Fundamentally, though, .NET My Services's philosophy is that if you can speak SOAP and can access a Kerberos library, you can talk to .NET My Services from any platform, in any language, and on any device.

.NET My Services Service Structure

Now that you have a greater understanding of how SOAP and HSDL interact with .NET My Services services, it may help to look more closely at a particular service.

In this section, we'll examine a brief portion of the .NET contacts service to understand what elements you can manipulate, which nodes are accessible via your XPath queries, and what elements are required of the .NET contacts service and a contact entry. When you come to understand the basics of how a service is constructed, the .NET My Services XMI Manual becomes an extremely valuable resource as you perform more complex service operations. For the walk-through in this section, we'll use the following abbreviated XML contact element that you might place in your .NET contacts service:

<myContacts >     <contact visibility="...">         <name visibility="...">             <title></title>             <firstName></firstName>             <middleName></middleName>             <lastName></lastName>             <suffix></suffix>             <fileAsName></fileAsName>         </name>         <address visibility="...">             <officialAddressLine ></officialAddressLine>             <internalAddressLine ></internalAddressLine>             <primaryCity ></primaryCity>             <secondaryCity ></secondaryCity>             <subdivision ></subdivision>             <postalCode></postalCode>             <countryCode></countryCode>         </address>         <emailAddress visibility="...">             <address></address>             <friendlyName ></friendlyName>         </emailAddress>     </contact> </myContacts>

In this XML example, there are three primary elements (blue) within the particular unpopulated contact example. They are name, address, and emailAddress. With each of these elements, there are different requirements and options for predication in your XPath queries.

The name Element

For the name element, there are no required child elements. However, if present, you can use the elements firstName, lastName, and fileAsName (and their textual content) as predicates in your XPath queries. That is, if you have a contact fragment such as:

<contact>   <name> <firstName>Christopher</firstName> </name> </contact>

You can select this particular contact element using XPath:

<xpQuery select='/myProfile/contact[name/firstName="Christopher"]'/>

You select the contact element, but you use the firstName element as a predicate. In a .NET My Services service, not every XML node is addressable within an XPath query. That is, you may want to search your contacts by middleName, but .NET My Services will not allow you to create a predicate based on middleName.

The address Element

As for the address element, it is intended to represent a geographical address and not an electronic address (see emailAddress later). The address element also contains no required descendent elements. The address element allows for predication upon the changeNumber and creator attributes—both supplied by .NET My Services. In other words, you can't necessarily build an XPath query that selects address elements based on postal code. (Note: .NET My Services supports an extended set of XPath functionality detailed in the SDK documentation, including reshapers, which give you added support for sorting and ordering node sets.)

The emailAddress Element

The emailAddress element also allows you to predicate upon changeNumber and creator, but in addition, it allows you to predicate upon its child address element and friendlyName elements. If you had a contact fragment such as:

<contact>   <emailAddress>     <address>chrisaj@microsoft.com</address>   </emailAddress> </contact>

With the above XML, you could write an XPath query that selects a contact based on the e-mail address:

select="/myContacts/contact[emailAddress/address='chrisaj@microsoft.com']"

It's important to remember which element constitutes the selected one and which elements are part of the predicate. In this case, the contact element would be returned.

Service Specific Methods

In addition to the six fundamental commands supported by .NET My Services services, some services offer specific methods that are unique to their functionality. In this section, we'll examine a couple of these and understand the reason for their existence.

.NET calendar service

The .NET calendar service (which as of this writing is still in development) utilizes several service-specific methods to facilitate using the service. These methods are meant to reduce the amount of code that clients on any platform would need to write. For example, if you wanted to find days on someone's calendar when they were available, you would potentially have to query a great chunk of the XML and manipulate it accordingly to determine free days and busy days.

The getFreeBusyDays method allows you to query someone's calendar (provided you have been granted access by the user) for blocks of free time and busy time. For example, blocks of time may come back indicating things such as:

• Busy from 12pm to 3pm
• Free from 3pm to 6pm

Additional methods are in development, including:

• getCalendarDays—This method returns the calendar appointments and events between the supplied dates.
• getQuickView—This method is intended to communicate, within a given range of dates, the days that have more than one appointment and the days that have no appointments.
• setCalendarAttachment—This method allows you to store an attachment within the myCalendar service.
• getCalendarAttachment—This method allows you to retrieve an attachment that has previously been stored in the .NET calendar service.
• meetingUpdate—This method allows you to invite attendees to an event.

The .NET calendar service is still in development, and this is by no means a comprehensive list of its exposed methods. Additionally, many other .NET My Services services feature service-specific methods as well. These are detailed in the XMI Manual.

The XMI Manual

The XMI Manual is the definitive reference for HSDL, service schemas, and particular service-specific methods. A current snapshot of the XMI Manual makes up the rest of this book. When developing your applications with the .NET My Services SDK, you can refer to the XMI Manual to better understand the XML required within a particular service document or to learn how to fine tune your HSDL commands across all services.

This chapter is provided in this book in preliminary form. When published in the forthcoming title (Spring/Summer 2002), the maturity of .NET My Services will have increased and this chapter will contain more detailed information.