Abstract

Windows Azure is a cloud service platform from Microsoft. The Force.com Toolkit for Azure makes it easy for you to leverage Force.com from Windows Azure. The toolkit is designed to be included within your existing Azure applications, and makes it easy for you to make API calls back to the Force.com platform. This article demonstrates how to get started using the Force.com toolkit for Azure.

Getting Started

First, download the Azure toolkit to your local drive. Within an existing Azure project, you can simply add the toolkit to your solution:

  1. Right Click on project within Solution Explorer
  2. Select "Add" and "Existing Project"
  3. Select and add the "DataBaseDotCom" project file
  4. Add "DataBaseDotCom" as a reference in your Web Role

Addproject.png


The toolkit should now be available within your solution. To enable the toolkit, add the following service model to your Web.Config:

<system.serviceModel>
    <bindings>
      <basicHttpBinding>
        <binding name="SoapBinding" closeTimeout="00:01:00" openTimeout="00:01:00"
            receiveTimeout="00:10:00" sendTimeout="00:01:00" allowCookies="false"
            bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard"
            maxBufferSize="65536" maxBufferPoolSize="524288" maxReceivedMessageSize="65536"
            messageEncoding="Text" textEncoding="utf-8" transferMode="Buffered"
            useDefaultWebProxy="true">
          <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384"
              maxBytesPerRead="4096" maxNameTableCharCount="16384" />
          <security mode="Transport">
            <transport clientCredentialType="None" proxyCredentialType="None"
                realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
          </security>
        </binding>
      </basicHttpBinding>
    </bindings>
    <client>
      <endpoint address="https://login.salesforce.com/services/Soap/u/20.0"
          binding="basicHttpBinding" bindingConfiguration="SoapBinding"
          contract="DBDCReference.Soap" name="Soap" />
    </client>
  </system.serviceModel>

Logging Into Salesforce

To allow the toolkit to have a easily configurable login, add the following to your ServiceDefinition file:

<Setting name="DbDotComConnectionString" />

And configure it within ServiceConfiguration with your username, password and (if necessary) token:

<Setting name="DbDotComConnectionString" value="UserName=;password=;token=;endpoint=" />

Once configured, you can create client from the toolkit and save the resulting context into session:

// BEGIN Login Example
DatabaseDotComClient client = new DatabaseDotComClient(DatabaseDotComContext.FromConfigurationSetting("DbDotComConnectionString"));
// END Login Example
Session.Add("context", client.context);

Otherwise, you can also login by passing in username, password and token to the context itself:

DatabaseDotComClient client = new DatabaseDotComClient()// END Login Example
client.contxt = client.login("username","password","token");
Session.Add("context", client.context);

Managing CRUD

With a successful login, you can retrieve the client and context to perform queries. For instance, to pull account information from existing contacts and then bind the results to an existing GridView:

DatabaseDotComContext context = (DatabaseDotComContext)Session["context"];
DatabaseDotComClient client = new DatabaseDotComClient(context);

DatabaseDotCom.DatabaseDotComClient.QueryResult qr = client.Query("Select Id, Name, Account.Name, Account.Industry, Account.Id From Contact");

GridView1.DataSource = qr.GetDataSet();
GridView1.DataBind();

Creating a new record requires create a DBCObject of the specific type, setting the attributes of the object and then calling the create method from DatabaseDotComClient:

DatabaseDotComContext context = (DatabaseDotComContext)Session["context"];
DatabaseDotComClient client = new DatabaseDotComClient(context);

// BEGIN Create Example
outputbox.Text += "Starting Create Sample..." + Environment.NewLine;
DatabaseDotComClient.DBCObject newAccount = new DatabaseDotComClient.DBCObject("Account");
newAccount.SetStringField("Name", "Azure Test Account");
newAccount.SetStringField("Industry", "Technology");
DatabaseDotCom.DBDCReference.SaveResult sr;
newAccount = client.Create(newAccount, out sr);
outputbox.Text += "Create was successful, new id is: " + newAccount.Id + Environment.NewLine + Environment.NewLine;

Or if you need to update a record, be sure to set the Id and then call Update.

newAccount.Id = '000000000';
newAccount.SetStringField("Industry", "Agriculture");
DatabaseDotCom.DBDCReference.SaveResult sr;

newAccount = client.Update(newAccount, out sr);

There are three options for deleting records. The first is that you can use an array of Id's and hand that to DeleteByIds:

// BEGIN Delete Example
DatabaseDotComContext context = (DatabaseDotComContext)Session["context"];
DatabaseDotComClient client = new DatabaseDotComClient(context);
DatabaseDotComClient.QueryResult accountQuery = client.Query("Select Id From Account Where Name = 'Azure Test Account'");

string[] ids = new string[accountQuery.records.Length];
for (int i = 0; i < ids.Length; i++)
{
  ids[i] = accountQuery.records[i].Id;
 }
 DatabaseDotCom.DBDCReference.DeleteResult[] results = client.DeleteByIds(ids);
 outputbox.Text += "Delete success result is: " + results[0].success +  Environment.NewLine + Environment.NewLine;        


Or by handing an array of records:

DatabaseDotComContext context = (DatabaseDotComContext)Session["context"];
            DatabaseDotComClient client = new DatabaseDotComClient(context);
            DatabaseDotComClient.DBCObject newAccount = new DatabaseDotComClient.DBCObject("Account");
            newAccount.SetStringField("Name", "Azure Test Account");
            newAccount.SetStringField("Industry", "Technology");
            DatabaseDotCom.DBDCReference.SaveResult sr;
            newAccount = client.Create(newAccount, out sr);

            DatabaseDotComClient.QueryResult accountQuery = client.Query("Select Id From Account Where Name = 'Azure Test Account'");
            DatabaseDotCom.DBDCReference.DeleteResult[] results = client.DeleteObjects(accountQuery.records);

Or by simply passing in a query:

DatabaseDotComContext context = (DatabaseDotComContext)Session["context"];
            DatabaseDotComClient client = new DatabaseDotComClient(context);
            DatabaseDotComClient.DBCObject newAccount = new DatabaseDotComClient.DBCObject("Account");
            newAccount.SetStringField("Name", "Azure Test Account");
            newAccount.SetStringField("Industry", "Technology");
            DatabaseDotCom.DBDCReference.SaveResult sr;
            newAccount = client.Create(newAccount, out sr);

            DatabaseDotComClient.QueryResult accountQuery = client.Query("Select Id From Account Where Name = 'Azure Test Account'");
            DatabaseDotCom.DBDCReference.DeleteResult[] results = client.DeleteByQueryResult(accountQuery);
            outputbox.Text += "Delete success result is: " + results[0].success + Environment.NewLine + Environment.NewLine;

Summary

The Azure toolkit offers a quick solution to developers wishing to merge or manipulate Force.com data with their existing Azure solutions. It provides the ability to perform basic CRUD and query functions, along with several utility methods.

References

About the Authors

Dave Carroll heads the Developer Evangelism team at Salesforce.com and wrote the Azure Toolkit and sample code.

Josh Birk is a Developer Evangelist at Salesforce.com and wrangler of code for everything from Ruby to Flex. Follow up with him on the Force.com blog or via Twitter.