Essential SharePoint 

10.4. Using URL Commands

URL commands get XML results from a SharePoint server through HTTP GET requests . You invoke the commands by specifying them as query strings in an address that has this form:

    http://server/subsite/_vti_bin/owssvr.dll?Cmd=cmdname&param=value&param=value ...

URL commands don't alter the content database, so they don't require authentication. The RPC protocol provides a similar approach, but uses HTTP POST instead of GET, and so can include authentication information and thus change content. Table 10-6 lists the commands that can be invoked through HTTP GET.

The List and View parameters in Table 10-6 are specified as GUIDs. See the following section, "Getting GUIDs," for how to get those values from the list or view names . The URL commands also accept the set of optional parameters in Table 10-7 to modify the returned results.

Table 10-6. SharePoint URL commands

Table 10-7. URL optional parameters

The HitCounter command is special. It renders an image used in an img element as shown here: <img src= "../_vti_bin/owssvr.dll?Cmd=HitCounter&Page=TestPages/URLDemo.aspx&Image=4&Digits=3">

10.4.1. Getting GUIDs

The List and View parameters of the URL commands are the unique identifiers (GUIDs) SharePoint uses internally. There's no URL command to get a GUID from a name, so you have to use the SharePoint object model or a web service to get the values. The following sections demonstrate how to get the List and View GUIDs in these three different scenarios:

• Server .NET code in a web part using the SharePoint object model

• Remote .NET code using web services

• Remote VBA code using web services

The return values of all the procedures are the same, but as you will see from the code, how you get the results varies.

10.4.1.1 Using SharePoint objects

If you're working within SharePoint, you can get GUIDs through the SharePoint object model. The following procedures get a reference to the current web using the GetContextWeb shared method, then use that object to get the list or view by name from the Lists or Views collections. The ID property is a GUID, which must be converted to a string in order to be used from the URL command:

    ' Requires: Imports Microsoft.SharePoint.Webcontrols
    Function GetListGuid(ByVal lName As String) As String
        Try
            ' Get the web from the current context.
            Dim web As SPWeb = SPControl.GetContextWeb(context)
            ' Get the list by name.
            Dim lst As SPList = web.Lists(lName)
            ' Get the GUID of the list.
            Dim guid As System.Guid = lst.ID
            ' Format the GUID as a string.
            Return ("{" & guid.ToString & "}")
        Catch ex As Exception
            Debug.Write(ex.Message)
            Return ""
        End Try
    End Function

    Function GetViewGuid(ByVal lName As String, _
      ByVal vName As String) As String
        Try
            ' Get the web from the current context.
            Dim web As SPWeb = SPControl.GetContextWeb(context)
            ' Get the view by name.
            Dim view As SPView = web.Lists(lName).Views(vName)
            ' Get the GUID of the list.
            Dim guid As System.Guid = view.ID
            ' Format the GUID as a string.
            Return ("{" & guid.ToString & "}")
        Catch ex As Exception
            Debug.Write(ex.Message)
            Return ""
        End Try
    End Function

The error handling in these and subsequent procedures is very basic and simply returns "" if the list or view was not found. You may want to change that in your own code.

10.4.1.2 Using web services (.NET)

The Lists web service GetList method returns an XML description of the list, which contains an ID attribute with the list's GUID. You can use SelectSingleNode to extract the ID attribute from the XML, as shown here:

    ' Requires a Web reference to the Lists.asmx.
    Function GetListGUID(ByVal lName As String) As String
        Dim xn As Xml.XmlNode, lws As New Lists.Lists
        Try
            ' Get the XML result from the web service.
            xn = lws.GetList(lName)
            ' Get the GUID (it's the ID attribute of the root element).
            Return xn.SelectSingleNode("//@ID").InnerText
        Catch ex As Exception
            Return ""
        End Try
    End Function

The Views web service GetViewCollection returns an XML description listing the views available for a list. Each view has a Name attribute containing the GUID of the view. In order to extract that information, you need to find the view by its DisplayName attribute using an XPath expression in SelectSingleNode as follows :

    ' Requires a Web reference to the Views.asmx.
    Function GetViewGUID(ByVal lName As String, ByVal vName As String) As String
        Dim xn As Xml.XmlNode, vws As New Views.Views
        Try
            ' Get the XML result from the web service.
            xn = vws.GetViewCollection(lName)
            ' Get the GUID (it's the Name attribute)
            ' where @DisplayName matches the view name.
            Return xn.SelectSingleNode("//*[@DisplayName='" & _
              vName & "']/@Name").InnerText
        Catch ex As Exception
            Return ""
        End Try
    End Function

10.4.1.3 Using web services (VBA)

Getting the GUIDs from VBA is similar to using the web services from .NET; however, the XML objects and error handling are different than those available in .NET:

    ' Requires web reference to Lists.asmx.
    Function GetListGUID(lName As String) As String
        On Error Resume Next
        Dim lws As New clsws_Lists
        Dim xn As IXMLDOMNodeList, guid As String
        ' Get the list.
        Set xn = lws.wsm_GetList(lName)
        ' Extract the GUID (it's the ID attribute).
        guid = xn(0).selectSingleNode("//@ID").Text
        ' Return "" if not found.
        If Err Then guid = ""
        ' Return the GUID.
        GetListGUID = guid
    End Function

    ' Requires web reference to Views.asmx.
    Function GetViewGUID(lName As String, vName As String) As String
        On Error Resume Next
        Dim vws As New clsws_Views
        Dim xn As IXMLDOMNodeList, guid As String
        ' Get the list's views.
        Set xn = vws.wsm_GetViewCollection(lName)
        ' Extract the GUID (it's the Name attribute).
        guid = xn(0).selectSingleNode("//*[@DisplayName='" & _
          vName & "']/@Name").Text
        ' Return "" if not found.
        If Err Then guid = ""
        ' Return the GUID.
        GetViewGUID = guid
    End Function

10.4.2. Executing URL Commands

You can use the URL commands as part of a link rendered on a page. For example, the following link displays the schema of a list:

    <a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=ExportList&List={70F9FF01-15E5-4129-A370-9A31090204E9}">Show list schema</a>

Or you can get the resulting XML in code using the .NET XML objects, as shown here:

    ' .NET: Use URL protocol to get a list's XML.
    Function GetListSchema(ByVal lName As String) As String
        Dim xdoc As New Xml.XmlDocument
        Dim guid As String = GetListGUID(lName)
        ' Create a reader for the URL.
        Dim xr As New Xml.XmlTextReader("http://wombat1/_vti_bin/owssvr.dll" & _
          "?Cmd=ExportList&List=" & guid)
        ' Load the response.
        xdoc.Load(xr)
        ' Return the XML as a string.
        Return xdoc.OuterXml
    End Function

Here's the same code in VBA:

    ' VBA: Use URL protocol to get a list's XML.
    Function GetListSchema(ByVal lName As String) As String
        Dim guid As String, xdoc As New DOMDocument
        guid = GetListGUID(lName)
        ' Load the response.
        xdoc.Load ("http://wombat1/_vti_bin/owssvr.dll" & _
          "?Cmd=ExportList&List=" & guid)
        ' Return the XML as a string.
        GetListXML xdoc.Text
    End Function

You can experiment with the URL commands to get the right combination of parameters. It is often easier to compose the command in the browser's address bar or as an HTML link before using it in code. For example, the first link below displays the visible list items in XML, whereas the second includes all of the hidden fields because it includes the parameter Query=* :

    <a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=Display&List={70F9FF01-15E5-4129-A370-9A31090204E9}&XMLDATA=TRUE">Display list XML (minimal)</a><br>

    <a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=Display&List={70F9FF01-15E5-4129-A370-9A31090204E9}&XMLDATA=TRUE&Query=*">Display list XML (full)</a>

For complex queries, it is often easier to use web services or RPC.