Table of Contents

1. Prerequisites

This tutorial assumes that you are familiar with the Slazure prerequisites, C# programming, and the Microsoft Azure DocumentDB.

1.1 Installing Slazure

Adding Slazure to your Visual Studio is done using NuGet.

Right-click your Visual Studio solution and select 'Manage NuGet Packages for Solution' in the context menu. Alternatively, you can type 'Install-Package Azure.DocumentDB.Slazure' in the NuGet Package Manager Console.

Unspecified
Open the NuGet Package Manager

Make sure that the package source is set to 'nuget.org', then Search for 'Azure.DocumentDB.Slazure' in the NuGet Package Manager. Select the appropriate Slazure package and version according to your preferences once the query result set has returned. After you click the 'Install' button you must agree to some license agreements, after which Slazure is added to your Visual Studio solution.

Unspecified
Install Slazure using NuGet

2 Getting started

A programmer develops Slazure-based software using Visual Studio and a .NET compatible programming language like C# or VB.NET.

2.1 Adding Slazure namespaces

After the Slazure NuGet package has been installed you should add the Slazure namespaces shown below.

using SysSurge.Slazure.AzureDocumentDB;
using SysSurge.Slazure.AzureDocumentDB.Linq;
using SysSurge.Slazure.Core.Linq.QueryParser;

2.2 Connecting to your database server

You connect to your Azure DocumentDB using Slazure by specifying the Azure connection string in the constructor like below. This will return a dynamically typed object which you can use to access your database server. Exaple follows below:

dynamic storage = new DynStorage("URL=https://contoso.documents.azure.com:443/;DBID=DDBExample;TOKEN=VZ+qKPAkl9TtX==");

Alternatively, if you plan to use the proprietary Slazure Linq provider, then you should rather use the QueryableStorage<TData> class constructor since this class includes the Linq provider - it includes all the functionality of DynStorage class as it inhertits from it. Example follows below:

dynamic storage = new QueryableStorage<DynDocument>("URL=https://contoso.documents.azure.com:443/;DBID=DDBExample;TOKEN=VZ+qKPAkl9TtX==");

2.3 Collections

2.3.1 Accessing a collection

You access Azure DocumentDB collections using either DynStorage or QueryableStorage<TData> class. All work with Slazure collections is done through the DynCollection class.

If you know the name of the collection when you write your code you can access it directly using a dynamic method with the collection name, in the example below we access a collection named "ExampleMessagesCollection":

dynamic messagesCollection = storage.ExampleMessagesCollection;

Alternatively, if you don't know the name at build-time then you can access the collection using the DynCollection class constructor and specify the collection name there; example follows below:

DynStorage storage = new DynStorage("URL=https://contoso.documents.azure.com:443/;DBID=DDBExample;TOKEN=VZ+qKPAkl9TtX==");
dynamic messagesCollection = new DynCollection(storage.DocClient, storage.DatabaseClient, "ExampleMessagesCollection", storage.ConnectionInfo);

2.3.2 Creating a new collection

With Slazure, you automatically create Azure DocumentDB collections when you access them if the collection does not already exists.

2.3.3 Deleting a collection

You delete an existing Azure DocumentDB collection by using the DynStorage.Delete() method while specifying the collection name of the collection that you want to delete from the database. Nothing happens if the collection does not exists. In the follwing example we delete a collection named "OldCollection" from the Azure DocumentDB database:

dynamic storage = new DynStorage("URL=https://contoso.documents.azure.com:443/;DBID=DDBExample;TOKEN=VZ+qKPAkl9TtX=="); 
storage.Delete("OldCollection");

2.3.4 Listing collections

You can list all Azure DocumentDB collections using the DynStorage.Collections property, this will return collections as DocumentCollection objects. In the example implementation that follows, we first need to add a new namespace:

using Microsoft.Azure.Documents;

, before we start accessing DocumentCollection objects:

List<string> GetListOfCollectionIds()

    List<string> collectionIds = new List<string>();
    DynStorage storage = new DynStorage("URL=https://contoso.documents.azure.com:443/;DBID=DDBExample;TOKEN=VZ+qKPAkl9TtX==");

    foreach (CloudTable collection in storage.Collections)
    {
        collectionIds.Add(collection.Id);
    }

    return collectionIds;
}

2.4 Documents

2.4.1 Accessing an document

You access Azure DocumentDB documents by either using DynCollection.Document() method, or querying for documents using the Slazure Linq Provider; both returns a DynDocument class which is also dynamically typed. When you use the DynCollection.Document() method you identify an document using its id property:

// Get a reference to DocumentDB
dynamic storage = new DynStorage("URL=https://contoso.documents.azure.com:443/;DBID=DDBExample;TOKEN=VZ+qKPAkl9TtX==");

// Get reference to the ExampleMessagesCollection collection, it's created if it doesn't already exist
dynamic employeesCollection = storage.exampleEmployees;

// Get a reference to an  document using its id to identify it
var employee = employeesCollection.Document("Doe_Jane");

// Write Jane Doe's salary to the console
Console.WriteLine(employee.FullName + "'s salary is $" +  employee.Salary + " USD/yr");

The following example does the same as the one above only this time using the Slazure Linq provider:

// Get a reference to DocumentDB
dynamic queryableStorage = new QueryableStorage<DynDocument>("URL=https://contoso.documents.azure.com:443/;DBID=DDBExample;TOKEN=VZ+qKPAkl9TtX==");

// Get reference to the ExampleMessagesCollection collection, it's created if it doesn't already exist
QueryableCollection<DynDocument> queryableEmployeesCollection = queryableStorage.exampleEmployees;

// Get a reference to an  document using its id to identify it
var employeeQuery =
    queryableEmployeesCollection.Where("id = @0""Doe_Jane")
    .Select("new(FullName, Salary)");

dynamic employee = employeeQuery.Cast<dynamic>().First();

// Write Jane Doe's salary to the console
Console.WriteLine(employee.FullName + "'s salary is $" +  employee.Salary + " USD/yr");

2.4.2 Creating a new document

With Slazure, you create Azure DocumentDB documents when you call the DynDocument.Save() method on the document object in question. The following example shows how we create a new employee document for John Doe by calling the DynDocument.Save() method:

// Get a reference to DocumentDB
dynamic storage = new DynStorage("URL=https://contoso.documents.azure.com:443/;DBID=DDBExample;TOKEN=VZ+qKPAkl9TtX==");

// Get reference to the ExampleMessagesCollection collection, it's created if it doesn't already exist
dynamic employeesCollection = storage.exampleEmployees;

// Define a new document using an id
var employee = employeesCollection.Document("Doe_Jane");

// Add some values to the employee document
employee.FullName = "John Doe";
employee.Salary = 60000;

// Save the new document to the Azure Collection Storage
employee.Save();

2.4.3 Deleting an document

You delete a document using the DynCollection.Delete() method

2.4.4 Listing documents

You list documents using the Slazure Linq provider and the SysSurge.Slazure.AzureDocumentDB.Linq namespace.