August 25, 2010

Working with Windows Azure Cloud Data in Delphi XE and C++Builder XE

Here's an excerpt from the Delphi XE and C++Builder XE documentation that gives further details on the new components for working with Windows Azure. You can see an example of this in the RAD Studio XE Sneak Preview 3 video.

Components for working with Windows Azure accounts are shipped with RAD Studio XE. Windows Azure (not to be confused with SQL Azure) allows you to store and manage Blobs, Queues of messages, and Tables of data on the Azure cloud. Once you have created an account, you can use the corresponding components found under the Microsoft Azure section of the Tool Palette. The available Azure components are: TAzureTableManagementTAzureQueueManagement, and TAzureBlobManagement. There is also a component called TAzureConnectionString, which takes into consideration information for connecting to your Windows Azure account. All these components use the Windows Azure REST API to manage the features that come with each of these services.
Azure components are useful for any developer who wants to make an application that manages a Windows Azure account. If used programmatically, the application itself could use information from the end-user's Azure account.


The TAzureConnectionString component is used to provide Azure connection information like AccountKey,AccountName, and Protocol.
Every Azure component from the Tool Palette requires a TAzureConnectionString placed on the same form, to provide Azure connection parameters.


To use a TAzureQueueManagement component, drop it on a form, and then drop aTAzureConnectionString onto the form as well. Type your AccountKey and AccountName into the appropriate properties of the TAzureConnectionString component. The next step is to set the ConnectionInfo property of the TAzureQueueManagement component to use this TAzureConnectionString. That is all you need to do in order to set up the TAzureQueueManagement component. However, you can also choose to set the Active property to True on the component, when the form is created. If you don't do this, then there will be a context menu item on the component at run time to activate it.
Once the component is running and activated, you can right-click the root node to add a new Queue or to refresh the current list of queues. With Windows Azure, you can have many queues, and each queue can have many messages, although the REST API, and therefore the TAzureQueueManagement component, is limited to showing only the first 100 messages of each queue. There is no guarantee the list you are looking at is in sync with the server any time after it is populated. At any time, to get the most current list of queues/messages, refresh the component from the context menu.
Note: When adding a queue, you need to specify a name that is at least 3 characters long, all lowercase (the component will automatically do this for you), and containing only letters, numbers, and/or hyphens (-).
On each queue node, you can choose to remove the queue, clear all messages from the queue, or add a message to the queue. A message is a string that has been pushed into the queue to serve whatever purpose the consumer of the queue uses it for. Unless you are clearing all the queue messages, only one message can be removed at a time. You also have the option, from this node, to refresh only this specific queue.
On the first (top) message node of a queue, you have the context menu option that can be used to remove it. This displays the message and then the next message in line becomes the new top message, as expected.


The Azure table component is a bit more complex than TAzureQueueManagement, but the setup is exactly the same. First drop theTAzureTableManagement component on the form, then drop the connection string component. Make sure you add connection information to the TAzureConnectionString, connect the two components, and then activate the table component.
Once you have your application running and the table component activated, you can right-click the root node to add a new table or to refresh the list of tables.
Note: When naming a table, make sure you do not start with a number; only letters are allowed as first character. Table names follow the naming guidelines listed above for queue names, but hyphens (-) are not supported in the name.
On each table node, there are additional context menu items for deleting the selected table or viewing the table's data in another dialog box. You can also bring up this table dialog by double-clicking the table node, or by holding the SHIFT key while pressing the ENTER key.

Table Data Dialog

The Table Data Dialog has, on the left, a list of all table rows. When you select a row, the table on the right will be automatically populated. The keys of this table will be the row's column name, and the value will be the value stored in the cell of the table (specific row and column).
Note: Windows Azure tables have no schema. This means that each row in the table can have a completely unique set of columns. For example, the first row may have 3 columns, while the second row may have 50 columns. If you want the table to behave like a standard Database table, then you need to manually enforce a specific schema.
To add a new row to the table, right-click the left list and choose to create a new Entity. The table on the right will be populated with two items,RowKey and PartitionKey. These two columns are required for all table rows. In this way, the row can be uniquely identified within the table. You can edit the values for RowKey and PartitionKey by right-clicking them and choosing to edit the property. This option is only available forRowKey and PartitionKey when you create a new row. Once you have committed the row for the first time, you cannot change the value of these properties.
Another option on the right table available while adding a new Entity (row) is creating a new property. Doing this will bring up the same dialog as the edit context menu item does. You will specify in this dialog the name of the property, the value, and the data type. Basic validation is done here to reduce the risk of you entering a value and/or datatype combination that is invalid.
Note: Even if you pass input validation, the value/datatype pairing you choose may still fail when you attempt to commit the new (or modified) row to the server. If this happens, you may lose data you had entered for that row before committing.
After making the changes to the new row, press Commit to push the changes to the server.

Filtering the List

Filtering the list is another action you can perform with the list on the left side of the table data dialog.
Notice that above the table row list there is a filter field. You can type in a value and validate it by pressing the ENTER key. In this way you filter the list to show only the rows that have that value as either their RowKey or PartitionKey. However, note that no partial matches or wild cards are supported in the Azure REST API, so the value you enter needs to be an exact match.
If you want to match on more than one Column (property) of the row, you can use the ADVANCED FILTER option. Note that on theTAzureTableManagement component there is a property, AdvancedFilterPrefix, which by default has a value of ~. In the table data dialog's filter field, you can enter something like:

~RowKey eq '1' and PartitionKey eq '1'

You can match on any column this way, not just PartitionKey and RowKey. If the datatype of the column is a string, you need to use single quotation marks around the value in the filter. If it is a number, you must use no quotation marks at all. RowKey and PartitionKey are always string types.

Importing Rows

To import rows, you have to select the context menu item for importing entities, which allows you to choose a text file to read the rows from. The text file needs to have a single JSON Value as its content.
The format of the file is as follows:

{"RowKey":"row1","PartitionKey":"Imported","AnyKeyName":"Hello World!"},

Note that the format previously shown describes a JSON Array, where each item in the array is a JSON Object. Each JSON Object must contain a property for RowKey and PartitionKey. Any other property has its key as a string following the naming convention for a table column. The value of the key is either a string (meaning the column is of string data type) or a JSON Array of size 2, where the value at index 0 is the string representation of the column value, and the value at index 1 is the data type of the column.
Note: If one or more rows from the text file cannot be imported, the text is skipped and the process continues for the rest of the rows, if they can be imported. In other words, it is not an all-or-none import.


The TAzureBlobManagement component is used to manipulate blobs (or Binary Large Objects). To use the TAzureBlobManagementcomponent, drop it on a form. Then drop the TAzureConnectionString component from the Tool Palette. Specify connection information in the TAzureConnectionString component, then connect both components. Do not forget to activate the Azure Blobs table.
Once you have your application running and the blob component activated, you can right-click the root node to add a new blob or to refresh the list of blobs.
Note: Naming conventions are the same as for the table component. Hyphens (-) are not allowed within the name.
Other operation options available while the application is running and you are within a TAzureBlobManagement component are: Create ContainerCopy BlobBlock Blob PropertiesCreate Block BlobCreate Snapshot Blob, and Page Blob.

No comments: