Selecting attributes to return in an enumeration

  • Article

In this post I show how to select specific attributes to return during an enumeration.  The purpose of this feature is to limit sending extra data over the wire.  This is an optional extension we added to WS-Enumeration for convenience.  You do not need to use this feature to use our enumeration endpoint.

Consider that you are building a list view of Person objects.  To build this list you need two or three attribute values: ObjectID, DisplayName, and maybe Title.  Using enumerate normally you would get back every attribute on the person.  It could be particularly excessive if the person has a photo uploaded.  With the selection feature you can ask enumerate to return only ObjectID, DisplayName, and Title.  If the user selects a person in the list view, you can then get all of the attributes using WS-Transfer Get.

How does it work?  Add one rm:Selection element to wsen:Enumerate in the Enumerate request for each attribute you wish to “select.”  If an rm:Selection element is not present, the Enumerate operation returns all attributes as normal.  If an rm:Selection element is present, the Enumerate operation only returns the attributes included in rm:Selection elements.

Here’s an example of selecting only the DisplayName and ObjectID of person objects:

<?xml version = "1.0" encoding ="utf-8"?>

<s:Envelope xmlns:s = "http://www.w3.org/2003/05/soap-envelope">

    <s:Header>

        <a:Action s:mustUnderstand = "1" xmlns:a ="http://www.w3.org/2005/08/addressing">http://schemas.xmlsoap.org/ws/2004/09/enumeration/Enumerate</ a:Action >

     </s:Header>

    <s:Body>

        <Enumerate xmlns = "http://schemas.xmlsoap.org/ws/2004/09/enumeration">

            <Filter Dialect = "http://schemas.microsoft.com/2006/11/XPathFilterDialect">/Person</ Filter>

            <MaxElements> 20</MaxElements>

            <MaxCharacters> 3668672</MaxCharacters>

            <Selection xmlns = "http://schemas.microsoft.com/2006/11/ResourceManagement">DisplayName</ Selection>

            <Selection xmlns = "http://schemas.microsoft.com/2006/11/ResourceManagement">ObjectID</ Selection>

        </Enumerate>

    </s:Body>

</s:Envelope>

 

Please note you can also sort by attributes.  Similar to rm:Selection, just add an rm:Sorting element to rm:Enumerate.  Rather than paste a one-off example below, allow me to point you to a collection of examples from a recent build of SOAP messages (the Topic 5 zip):

http://code.msdn.microsoft.com/imexsamples/Release/ProjectReleases.aspx

These are actual SOAP messages I picked off the wire of build 2313 (a build well after RC).  I cannot guarantee anything about these messages.

Hope this helps, and good luck exploring!