Slazure Online Resources

Table of Contents

1. Prerequisites

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

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 Slazure.MongoDB' 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 'Slazure.MongoDB' 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.MongoDB;
using SysSurge.Slazure.MongoDB.Linq;
using SysSurge.Slazure.Core.Linq.QueryParser;

2.2 Connecting to your database server

You connect to your MongoDB 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("mongodb://user:pass@example.org/MongoDBExample");

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>("mongodb://user:pass@example.org/MongoDBExample");

2.3 Collections

2.3.1 Accessing a collection

You access MongoDB 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 runtime then you can access the collection using the DynCollection class constructor and specify the collection name there; example follows below:

DynStorage storage = new DynStorage("mongodb://user:pass@example.org/MongoDBExample");
dynamic messagesCollection = new DynCollection(storage.StorageAccount, "ExampleMessagesCollection");

2.3.2 Creating a new collection

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

2.3.3 Deleting a collection

You delete an existing MongoDB 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 MongoDB database:

dynamic storage = new DynStorage("mongodb://user:pass@example.org/MongoDBExample"); 
storage.Delete("OldCollection");

2.3.4 Listing collections

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

using MongoDB.Bson;

, before we start accessing BsonDocument objects:

List<string> GetListOfCollectionIds()

    List<string> collectionIds = new List<string>();
    DynStorage storage = new DynStorage("mongodb://user:pass@example.org/MongoDBExample");

    foreach (BsonDocument collection in storage.Collections)
    {
        collectionIds.Add(collection["_id"].AsString);
    }

    return collectionIds;
}

2.4 Documents

2.4.1 Querying for documents

You query for MongoDB 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.

The following example uses the Slazure Linq provider to query for a document by its ID:

// Get a reference to MongoDB
dynamic queryableStorage = new QueryableStorage<DynDocument>("mongodb://user:pass@example.org/MongoDBExample");

// 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");

The following example uses the DynCollection.Document() method to query for a document using its _id property:

// Get a reference to MongoDB
dynamic storage = new DynStorage("mongodb://user:pass@example.org/MongoDBExample");

// 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");

You can write complex queries using operators like "and", "or", and "not" etc., see "Query filtering with Where" in the API documentation for a complete list of legal query filtering operators. Further more, Slazure supports projection-, paging-, ordering-, and grouping of query results.

The following example builds a table query that return employees that has a salary greater than $40k/year using a dynamic LINQ query filter and adds projection-, paging-, ordering-, and grouping to the query result set:

// C# example: .
QueryableTable<DynEntity> employeesTable = storage.Employees;
var employeeQuery = employeesTable
    // Query for salary greater than $40k and born later than early '95.
    .Where("Salary > 40000 and Birthdate >= DateTime(1995,15,3)")
    // Projection and aliasing.
    .Select("new(PartitionKey as Email, Birthdate, Name, Timestamp as RegisteredDate)")
    // Order result set by birthdate descending.
    .OrderBy("Birthdate desc")
    // Paging: Skip the first 5 and retrieve only 5.
    .Skip(5).Take(5)
    // Group result set on Birthdate and then on Name.
    .GroupBy("Birthdate", "Name");

// Use a dynamic type so that we can get access to the document's dynamic properties
foreach (dynamic employee in employeeQuery)
{
    // Show some information about the employee
    Console.WriteLine("The employee '{0}' was employed {1} and was born in {2}.",
        employee.Email, employee.RegisteredDate, employee.Birthdate.Year);
}

2.4.2 Creating a new document

With Slazure, you create MongoDB 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 MongoDB
dynamic storage = new DynStorage("mongodb://user:pass@example.org/MongoDBExample");

// 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.MongoDB.Linq namespace.

Published • Modified