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.
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:
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
[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 = userName;
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.
