Part 3: SQL Data Services – Creating an Authority


In Part 1, we were introduced to the concept of SQL Data Services (SDS) and the fundamental design. 
In Part 2, we looked at the options for authentication, data access and the SDS SDK (helpful tools).

In this entry we will look at using the SOAP interface to create an application to manipulate an Authority.  Note: You can also create Authorities, Containers and Entities using the st.exe utility which is part of the SDS SDK.

A Basic Application (SOAP)

Opening Visual Studio, create a new Console Application (in your language of choice).  All my samples are in C#, but I can help with VB.net or C++.net upon request (email me separately).

Ensure you add a project reference to ‘System.ServiceModel’.

Add a Service Reference

Our first goal is to create a Service Reference.   Specify the address as https://database.windows.net/soap/v1/ and change the default value (ServiceReference1) for Namespace to ssdsClient.

image

To create a Service Reference in Visual Studio 2005, refer to this document [http://msdn.microsoft.com/en-au/library/cc512437.aspx].

The service reference will create a config file in the project’s root folder.  Ensure the content of the config file is merged with any existing config file (if applicable).

Adding the reference also creates the objects we need to work with SDS.  The following image shows the objects exposed by the Service Reference:

image

Creating an Authority

Creating a new Authority is actually not terribly difficult, but needs to be handled in an intelligent fashion.  We will dissect the approach carefully.

Below is a small code sample which shows how to create a new Authority using the SOAP interface.

using (SitkaSoapServiceClient proxy = new SitkaSoapServiceClient("endPointName"))
{
  proxy.ClientCredentials.UserName.UserName = "[username]";
  proxy.ClientCredentials.UserName.Password = "[password]";

  // To target the "service" level you use the "empty" scope.
  Scope serviceScope = new Scope();
  // Create authority
  Authority auth = new Authority();
  auth.Id = "samples";
  proxy.Create(serviceScope, auth);
}

Let us review each line since this approach becomes very common for most SDS interactions.

The SitkaSoapServiceClient Class

SitkaSoapServiceClient proxy = new SitkaSoapServiceClient("BasicAuthEndpoint")

The end point name determines the authentication mechanism used to contact SDS.  In the example above, I’ve specified basic authentication.

When using Basic Authentication, the next step is to specify the username and password (as in the example quoted).

To use token authentication, you would specify "UsernameTokenEndpoint" (to obtain a security token) followed by either “CertificateTokenEndpoint” (for X.509 certificates) or ""CardSpaceTokenEndpoint" (for Windows CardSpace tokens).

Alternate (non-basic) authentication will be discussed at a later date.

Specifying Scope

The next step is to create a scope for our operation.  The scope is used to identify what part of the application (Authority/Container/Entity) our operation concerns.

In this case, to create a new Authority, we simple specify an empty scope (it’s going to be a service-level operation) and create a new Authority object.

Naming an Authority

Specifying an identifier (a string value) and passing it to the proxy’s Create method executes the process or requesting to create a new Authority (which includes creating a new DNS record, as the Authority will become a sub domain).

When you create an authority, the AuthorityId must contain only lowercase letters, numbers, or dashes. Within the service, each authority must have a unique id.

Scope serviceScope = new Scope();
// Create authority
Authority auth = new Authority();
auth.Id = "samples";
proxy.Create(serviceScope, auth);

If the call in the code above is successful the following URI would become valid: https://sample.data.database.windows.net/v1/ – to test that it is working, you can simply browse to this location in  a Web Browser.

Notes on the Initial Release

  • Authority deletion is not supported in the initial release.
  • After creating an authority, it make take up to of 10 seconds  for the host name of the authority to be registered with the DNS service.
  • Id is limited to 64 characters.
  • A valid user name and password are required for all service interactions. User credentials must be obtained from the SQL Data Services management portal before accessing the service.
  • When using SSL (e.g. HTTPS), both credentials and data are encrypted on the wire

    [From http://msdn.microsoft.com/en-us/library/cc512388.aspx]

    Fault Handling

    The majority of problems encountered will cause a FaultException or a CommunicationException to be thrown. 

    The code below is what I am currently using to trap situations where the Authority already exists, or there is a problem in creating the DNS record (the name may be inappropriate).

    catch (FaultException<Error> e)
    {
        if (e.Detail.StatusCode != ErrorCodes.EntityExists &&

                
    e.Detail.StatusCode != ErrorCodes.UnableToCreateDnsRecord)
        {
             //HandleException(e); //(use as appropriate)
        }
        Debug.WriteLine("Authority Exists");
        // Alternative: Log the message
    }

  • If you encounter a CommunicationException, chances are this is a connection issue and not an issue with SDS directly.  In this instance, you need to determine an appropriate course of action (this will be an application architecture consideration).

    Creating a Container

    Creating a container inside an Authority is almost the same as creating the Authority itself.

    The syntax is very similar with the exception that you specify the AuthorityId as part of the Scope.

    Refer to the example syntax below.  Note the use of Basic Authentication.

    using (SitkaSoapServiceClient proxy = new
           SitkaSoapServiceClient("BasicAuthEndpoint"))
    {
        proxy.ClientCredentials.UserName.UserName = u
    serName; 
        proxy.ClientCredentials.UserName.Password = password;

        // Identify scope. To create a container authority
        // must be in scope.
        Scope myAuthorityScope = new Scope();
        myAuthorityScope.AuthorityId = AuthorityId;
    // (e.g. “sample”)

        // Create a container
        Container c1 = new Container(); c1.Id = "NewContainer";
        proxy.Create(myAuthorityScope, c1);
    }

    Again, should the resulting call to proxy.Create() succeed, the following URI would be valid:
    https://<YourExistingAuthorityId>.data.database.windows.net/v1/<NewContainerId>
    or, as per the example: https://sample.data.database.windows.net/v1/NewContainer

    Fault Handling

    As with creating an Authority, we can trap FaultException and CommunicationException to determine the cause behind any failures.

    catch (FaultException<Error> e)
    {
        if (e.Detail.StatusCode != ErrorCodes.EntityExists)
        {
              //HandleException(e);
        }
        Debug.WriteLine("Container Exists");
        // Alternatively, log the exception
    }

    In the example above, I have trapped the “Entity Exists” exception, although you may prefer to handle this in another fashion.

    Summary

    In this entry, we’ve successfully set up a .Net application, added a Service Reference and implemented code which can successfully create an Authority and a Container.

    In the next entry, we will continue with this sample and create and query some Entities using this sample application.


  • About Rob Sanders

    IT Professional and TOGAF 9 certified architect with nearly two decades of industry experience, 18 years in commercial software development and 11 years in IT consulting. Check out the "About Rob" page for more information.

    Leave a comment

    Your email address will not be published. Required fields are marked *

    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>