Enzo Framework API Reference Guide

Transcription

1 Enzo Framework API Reference Guide This document provides a programmatic reference guide for the Enzo Framework API. BETA DOCUMENTATION Blue Syntax Consulting specializes in the Microsoft Azure platform and provides architectural and development guidance to corporations leveraging cloud computing technologies. Created by Blue Syntax Consulting Published on 1/19/2011 Copyright (C) Blue Syntax Consulting Page 1

2 For more information, contact us at Version Introduction The Enzo API Framework is a technology allowing developers to easily access their SQL Azure and SQL Server databases from existing or new applications in a way that facilitates scalability and performance. The Enzo API Framework provides a form of abstraction by presenting a logical layer that developers can use to select which databases should be selected to execute specific statements. Copyright (C) Blue Syntax Consulting Page 2

3 API Reference BSC.EnzoAzureLib.Batch.BatchOperator The BatchOperator class allows developers to send SQL commands asynchronously as a batch of commands in order to minimize roundtrips (which minimizes the use of connections from the connection pool) and frees the application thread to perform other tasks meanwhile. Constructors BatchOperator(Shard) The constructor requires a Shard object. Methods BatchFlush QueueNonQuery(string) QueueNonQuery(SqlCommand) QueueNonQueryAsynch(string) QueueNonQueryAsynch (SqlCommand) Flushes the commands found in the Queue Queues a T-SQL for execution Queues a SQL command for execution. The SqlCommand object cannot have any Queues a T-SQL asynchronously for optimum performance Queues a command asynchronously for optimum performance. The SqlCommand object cannot have any BatchExecutionDBGuid BatchExecutionMode BatchQueue Static BatchEvaluationInterval BatchSize BatchTimeout BatchXAbort Events OnBatchSubmitError OnBatchSubmitSuccess The database GUID to use when the execution mode is set to Auto Determines how the databases will be selected: Auto, Default and Next. Auto uses the BacthExecutionDBGuid to select the correct database. Default uses the default database on the shard. Next (the default setting) performs a round-robin selection of databases in the shard Returns a count of the number of commands pending Time interval between automatic flushes of commands (read-only) Number of T-SQL commands executed at the same time. Using 0 sends all the commands from the Queue (read-only) Command timeout when executing the commands (read-only) True to execute all the T-SQL commands with the XAbort option (readonly) Event raised when an error has been detected when executing the commands Event raised when commands have been successfully submitted Remarks When a new BatchOperator object is created, its internal timer starts automatically and its default execution mode is set to DBBatchExecutionMode.Next. The timer interval is derived from the Batch configuration settings in the Enzo Multitenant Management Console. When the BatchOperator object goes out of scope, the object attempts to flush all pending commands to the database(s). Copyright (C) Blue Syntax Consulting Page 3

4 The static properties are configured on the Enzo Multitenant Management Console under API Configuration -> Batch Settings. Changes to these settings may take effect automatically depending on the API Settings configuration. Example The following code example assumes a Shard Cluster called MYCLUSTER was created with a default Shard. The code also assumes a table called users exists with a field that has a column of type string. // Note: replace the connection string with valid values string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); BSC.EnzoAzureLib.Batch.BatchOperator bo = new BSC.EnzoAzureLib.Batch.BatchOperator(sc.DefaultShard); for(int i=0; i < 10; i++) bo.queuenonqueryasynch("insert INTO users VALUE 'John" + i.tostring() + "'"); Copyright (C) Blue Syntax Consulting Page 4

5 BSC.EnzoAzureLib.Batch.DBBatchExecutionMode This Enum is used to provide the BatchOperator a hint on how to select the database that will receive the batch operation. Enum Auto Default Next Uses the BacthExecutionDBGuid to select the correct database. The database GUID must belong to the shard specified through the constructor Default uses the default database on the shard Performs a round-robin selection of databases in the shard. This is the default behavior Copyright (C) Blue Syntax Consulting Page 5

6 BSC.EnzoAzureLib.DBLoadOptions This Enum is used to provide the Shard object a hint on how to select the database(s) that will receive a SQL statement through the ExecuteDataTable or the ExecuteNonQuery commands. If the information provided does not resolve to a database an exception will be thrown. This Enum is provided as part of the Shard.DBExecutionOption structure. Enum All Any Auto Default Next Specific Executes the statement against all the databases in the shard; ignores the Attributes and DatabaseGUID values provided in the Shard.DBExecutionOption structure. Executes the statement against any database in the shard that is selected through a list of attributes (the Attributes property of the Shard.DBExecutionOption structure) Executes the statement against zero, one or more databases in the shard selected through a list of attributes (the Attributes property of the Shard.DBExecutionOption structure) Default uses the default database on the shard Performs a round-robin selection of databases in the shard. This is the default behavior Uses the DatabaseGUID of Shard.DBExecutionOption to select the desired database. The database GUID must belong to the shard specified through the constructor Remark The ConnectionGuid value is calculated dynamically based on the content of the connection string. As a result it may change from time to time if the connection string is modified through the Enzo Multitenant Management Console. You should not store this Guid for use at a later time; it should be considered valid for a limited period of time. Copyright (C) Blue Syntax Consulting Page 6

7 BSC.EnzoAzureLib.LinqToShard.DataContext This class is used for the Linq to Shard feature; it is not meant to be used programmatically by your application code. When using the Linq to Shard feature, you will need to override the Base Class of the Linq to SQL Data Context by entering the fully qualified class name (BSC.EnzoAzureLib.LinqToShard.DataContext) as such: Copyright (C) Blue Syntax Consulting Page 7

8 BSC.EnzoAzureLib.Shard The Shard class encapsulates a list of databases and provides methods that can select or change records in one or more underlying databases. Constructors The Shard class operates under a Shard Cluster and can be selected by name, by the DefaultShard property of a Shard Cluster or by attribute. As a result it has no constructor. Methods ExecuteDataTable(SqlCommand,...) ExecuteDataTable(string,...) ExecuteNonQuery(SqlCommand,...) ExecuteNonQuery(string,...) ExecuteParallelRoundRobinLoad(List<SqlCommand>) Executes a command against one or more databases in parallel and returns a DataTable Executes a T-SQL query against one or more databases in parallel and returns a DataTable Executes a command against one or more databases in parallel Executes a T-SQL query against one or more databases in parallel Executes a list of commands in parallel against all the databases in the shard using a round-robin mechanism IsDefault Items Name ParentCluster ShardAttributes Static AutoRefresh ColIDName ConnectionRetryCount IncludeDBIDColumn MaxDOP SynchTimeout TTL True if the shard is the default shard in its Cluster Shard The list of databases and attributes assigned to each database; the password is removed The name of the shard The shard cluster this shard belongs to List of attributes assigned to this shard True if the shard automatically refreshes itself on a specific frequency (read-only) The column name automatically added to the DataTable returned by ExecuteDataTable in which the database GUID of a record is specified The number of retries performed automatically when trying to establish a database connection True if the ColIDName will be added to a DataTable returned by ExecuteDataTable The maximum number of parallel threads that will be used when calling ExecuteDataTable, ExecuteNonQuery and ExecuteParallelRoundRobinLoad (read-only) Forces the refresh of the Enzo API internal settings if the API is unable to apply the scheduled changes within this amount of time (read-only) Time during each refresh of the Enzo API internal settings (read-only) Copyright (C) Blue Syntax Consulting Page 8

9 Remarks By default the Enzo API Framework will automatically refresh itself, including the list of shards, and databases within each shard on a specific internal (TTL). To disable this feature set the AutoRefresh property to false by changing the API Configuration on the Enzo Multitenant Management Console. Certain static properties can be modified through code, such as the ConnectionRetryCount; however if the AutoRefresh setting is True, this value will be automatically overridden at the next refresh interval (TTL). As a result if you plan to modify any of the static properties at runtime, you should consider turning off the automatic refresh feature. The Items property returns a list of ShardConnection objects. Each ShardConnection object contains the connection string without the password, along with a list of attributes and values associated to each database connection. Calling the ExecuteDataTable or the ExecuteNonQuery method can be done by specifying either a T-SQL statement or a SqlCommand object. If the SqlCommand object has a collection of SqlParameters defined they will be used. However other properties of the SqlCommand object is not supported. Notably the Notification and Transaction properties are ignored. If the DBExecutionOption is not specified, statements are executed against all databases. Example The following code example assumes a Shard Cluster called MYCLUSTER was created with a default Shard. The code also assumes a table called users exists with a field that has a column of type string. // This code assumes you have created a Cluster called MYCLUSTER with a Default shard // Note: replace the connection string with valid values string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); // Create a user table against the default shard in all its underlying databases sc.defaultshard.executenonquery("create TABLE users (id int primary key, name nvarchar(25))"); // Insert records in a round-robin manner List<string> cmds = new List<string>(); for (int i = 0; i < 20; i++) cmds.add("insert INTO users VALUES ('John" + i.tostring() + "')"); sc.defaultshard.executeparallelroundrobinload(cmds); // Retrieve top 10 records across all databases; if DBExecutionOption is not specified // the statement will be executed against all databases Shard.QueryOptions qo = new Shard.QueryOptions(); qo.top = 10; qo.orderby = "name"; DataTable result = sc.defaultshard.executedatatable("select TOP 10 * FROM users ORDER BY name", qo); Copyright (C) Blue Syntax Consulting Page 9

10 BSC.EnzoAzureLib.ShardCluster The ShardCluster is the top level object in the Enzo Framework API. It encapsulates a list of shards and provides methods that can select or change records in one or more underlying shard databases. Constructors ShardCluster(string, string) The constructor requires a connection string to the Enzo Configuration database and the name of the Cluster to load. Methods ExecuteDataTable(SqlCommand,...) ExecuteDataTable(string,...) ExecuteNonQuery(SqlCommand,...) ExecuteNonQuery(string,...) Reload Executes a command against one or more databases in parallel and returns a DataTable; depending on the option one or more shards may be used to determine which databases are being considered for inclusion Executes a T-SQL query against one or more databases in parallel and returns a DataTable; depending on the option one or more shards may be used to determine which databases are being considered for inclusion Executes a command against one or more databases in parallel Executes a T-SQL query against one or more databases in parallel Reloads the definition of a shard cluster without waiting for the next refresh window DefaultShard Items Name ShardNames Events OnClusterDefinitionChanged OnClusterExpansionCompleted OnClusterExpansionStarting The default shard of the shard cluster, if any The list of shards in the shard cluster The name of the shard cluster The list shard names contained by this shard cluster Raised when the shard cluster is being reloaded due to a change detected in the Enzo Configuration database. Internal use only Internal use only Remarks It is necessary to create a Shard Cluster object before any feature of the Enzo API Framework can be used. The Shard Cluster loads its definition from the Enzo Configuration database when its constructor is called. As a result it is important that the Enzo Configuration database is accessible when declaring a Shard Cluster. Also, due to the relative intensive nature of loading this object it should be declared as a global variable in your application code if appropriate. SQL Statements are usually executed against one or more databases in a single shard. However in some cases it may be necessary to execute a command across shards. The ShardCluster class provides similar features than the Shard class through its ExecuteDataTable and ExecuteNonQuery methods. Copyright (C) Blue Syntax Consulting Page 10

11 If you disabled the AutoRefresh feature of the API you can force a refresh of the shard definition by calling the Reload method. If you enabled the AutoRefresh feature you can be notified when a refresh is taking place by subscribing to the OnClusterDefinitionChanged event. Although using the DefaultShard property simplifies application code you should be aware that this property could return a null reference if no default shard is assigned to a cluster. Example The following code example assumes a Shard Cluster called MYCLUSTER was created. string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); // Output the list of shards in the shard cluster foreach (Shard s in sc.items) System.Diagnostics.Debug.WriteLine(s.Name); // Return the list of database ids from all databases in all the shards of the cluster DataTable dt = sc.executedatatable("select db_id() as dbid"); Copyright (C) Blue Syntax Consulting Page 11

12 BSC.EnzoAzureLib.ShardLoadOptions This Enum is used to provide the Shard Cluster object a hint on how to select the shard(s) that will receive a SQL statement through the ExecuteDataTable or the ExecuteNonQuery commands. If the information provided does not resolve to a shard an exception will be thrown. This Enum is provided as part of the ShardCluster.ShardExecutionOption structure. Enum All Any Auto Default Next Specific Executes the statement against all the shards in the cluster; ignores the Attributes and ShardName values provided in the ShardCluster.ShardExecutionOption structure. Executes the statement against any shard in the cluster that is selected through a list of attributes (the Attributes property of the ShardCluster.ShardExecutionOption structure) Executes the statement against zero, one or more shards in the cluster selected through a list of attributes (the Attributes property of the ShardCluster.ShardExecutionOption structure) Default uses the default shard on the shard cluster Performs a round-robin selection of shards in the shard cluster. This is the default behavior Uses the ShardName of ShardCluster.ShardExecutionOption to select the desired shard Copyright (C) Blue Syntax Consulting Page 12

13 BSC.EnzoAzureLib.StaticDBAttributes This structure is returned by the Attributes property of the ShardConnection structure, which is itself returned by the Items property of the Shard class. It contains information about the attributes assigned to a database. Name ValueArray[] Value ValueRangeFrom ValueRangeTo AttributeType ConnectionGuid The name of the attribute An array of values assigned to the attribute The value assigned to the attribute The DateTime of the start date of the value The DateTime of the end date of the value Indicates which type the attribute is (SingleValue, Array, DateRange, RegEx) The database connection GUID to which this attribute is assigned Remarks The properties of this class are read only. They provide information of the list of attributes assigned to a database and their assigned values as specified in the Enzo Multitenant Management Console. The Name property is unique per database. If the AttributeType is SingleValue or RegEx, the value of the attribute will be stored in the Value field. If the AttributeType is DateRange the value is stored in the ValueRangeFrom and ValueRangeTo fields. If the AttributeType is Array the list of values is stored in the ValueArray field. The ConnectionGuid value is calculated dynamically based on the content of the connection string. As a result it may change from time to time if the connection string is modified through the Enzo Multitenant Management Console. Example The following code example assumes a Shard Cluster called MYCLUSTER was created and a default shard has been assigned to that shard cluster. // This code assumes you have created a Cluster called MYCLUSTER with a Default shard // Note: replace the connection string with valid values string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); // Output the list of shards attributes for the default shard foreach (Shard.ShardConnection s in sc.defaultshard.items) foreach(staticdbattributes attr in s.attributes) System.Diagnostics.Debug.WriteLine(attr.Name); Copyright (C) Blue Syntax Consulting Page 13

14 BSC.EnzoAzureLib.StaticShardAttributes This structure is returned by the ShardAttributes property of the Shard class. It contains information about the attributes assigned to a shard. Name ValueArray[] Value ValueRangeFrom ValueRangeTo AttributeType The name of the attribute An array of values assigned to the attribute The value assigned to the attribute The DateTime of the start date of the value The DateTime of the end date of the value Indicates which type the attribute is (SingleValue, Array, DateRange, RegEx) Remarks The properties of this class are read only. They provide information of the list of attributes assigned to a Shard and their assigned values as specified in the Enzo Multitenant Management Console. The Name property is unique per shard. If the AttributeType is SingleValue or RegEx, the value of the attribute will be stored in the Value field. If the AttributeType is DateRange the value is stored in the ValueRangeFrom and ValueRangeTo fields. If the AttributeType is Array the list of values is stored in the ValueArray field. Example The following code example assumes a Shard Cluster called MYCLUSTER was created and a default shard has been assigned to that shard cluster. // This code assumes you have created a Cluster called MYCLUSTER with a Default shard // Note: replace the connection string with valid values string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); // Output the list of shards attributes for the default shard foreach (StaticShardAttributes s in sc.defaultshard.shardattributes) System.Diagnostics.Debug.WriteLine(s.Name); Copyright (C) Blue Syntax Consulting Page 14

15 BSC.EnzoAzureLib.Shard.DBExecuteOption The DBExecuteOption is a structure allowing you to specify which databases are selected when running a database command. It is optionally passed as a variable to the ExecuteDataTable and ExecuteNonQuery methods of both the Shard and the ShardCluster objects. Attributes DatabaseGUID LoadOption The list of attributes identifying which database(s) are to be selected A specific database GUID to be selected The selection mode determining how the database(s) will be selected. This property takes a Shard.DBLoadOptions. Depending on the option selected, the Attribute and DatabaseGUID properties may or may not be used. Remarks This structure provides significant flexibility in selecting the databases against which a SQL statement needs to be executed. If this structure is not provided, the DBLoadOptions.All setting will be used. Example This example shows various ways to use this structure to select one or more databases to execute a SQL statement. // This code assumes you have created a Cluster called MYCLUSTER with a Default shard // Note: replace the connection string with valid values string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); // Executes a statement against all databases in the default shard (no DBExecuteOption is provided) sc.defaultshard.executenonquery("select GETDATE()"); // Executes a statement against the default database Shard.DBExecutionOption dbeo = new Shard.DBExecutionOption(); dbeo.loadoption = DBLoadOptions.Default; sc.defaultshard.executenonquery("select GETDATE()", dbeo); // Executes a statement against two databases, one after the other dbeo.loadoption = DBLoadOptions.Next; sc.defaultshard.executenonquery("select GETDATE()", dbeo); sc.defaultshard.executenonquery("select GETDATE()", dbeo); // Executes a statement against a specific database given its GUID dbeo.loadoption = DBLoadOptions.Specific; dbeo.databaseguid = sc.defaultshard.items[0].guid; sc.defaultshard.executenonquery("select GETDATE()", dbeo); // Executes a statement against databases with the City attribute of Boca Raton dbeo.loadoption = DBLoadOptions.Auto; dbeo.attributes.add("city", "Boca Raton"); sc.defaultshard.executenonquery("select GETDATE()", dbeo); Copyright (C) Blue Syntax Consulting Page 15

16 BSC.EnzoAzureLib.Shard.QueryOptions This structure allows you to perform simple operations on the resultset obtained from an ExecuteDataTable operation. Top OrderBy Returns a limited number of records from the aggregated resultsets Orders the aggregated resultsets by the column name(s) provided Remarks When executing a statement against two or more databases, recordsets are aggregated to form a single DataTable output. The query options provide a mechanism to alter the resultsets before they are returned from the ExecuteDataTable method call. When applying a Top condition, you should also consider adding the same Top condition to your SQL statement to limit the number of records returned by database to improve performance. If you specify both Top and OrderBy, you should consider applying both to the SQL statement. Example This example shows how to use the QueryOptions structure. // This code assumes you have created a Cluster called MYCLUSTER with a Default shard // Note: replace the connection string with valid values string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); Shard.QueryOptions qo = new Shard.QueryOptions(); qo.top = 20; qo.orderby = "name"; DataTable dt = sc.defaultshard.executedatatable("select TOP 20 * FROM users ORDER BY Name", qo); Copyright (C) Blue Syntax Consulting Page 16

17 BSC.EnzoAzureLib.ShardConnection This structure contains information about a database connection. It is returned by the Items property of a shard object. ConnectionString GUID Attributes The connection string of a database without the password information The GUID of the database The list of attributes assigned to the database (StaticDBAttributes) Remarks The GUID value is calculated dynamically based on the content of the connection string. As a result it may change from time to time if the connection string is modified through the Enzo Multitenant Management Console. Copyright (C) Blue Syntax Consulting Page 17

18 BSC.EnzoAzureLib.ShardCluster.ShardExecutionOption The ShardExecutionOption allows you to specify which shards should receive a SQL statement for processing. Attributes LoadOption ShardName The list of attributes identifying which shard(s) are to be selected The selection mode determining how the shard(s) will be selected. This property takes a ShardCluster.ShardLoadOptions. Depending on the option selected, the Attribute and ShardName properties may or may not be used. The name of a shard Remarks Each selected shard will then evaluate which database should be used to execute a statement. This structure is used against the ExecuteNonQuery and ExecuteDataTable methods of a ShardCluster object. Example // This code assumes you have created a Cluster called MYCLUSTER with a Default shard // Note: replace the connection string with valid values string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); // Execute the same statement on multiple shards, one at a time, against all their databases ShardCluster.ShardExecutionOption seo = new ShardCluster.ShardExecutionOption(); seo.loadoption = ShardLoadOptions.Next; sc.executenonquery("select GETDATE()", seo); sc.executenonquery("select GETDATE()", seo); sc.executenonquery("select GETDATE()", seo); Copyright (C) Blue Syntax Consulting Page 18

19 BSC.EnzoAzureLib.ShardCluster.EventResult This structure provides a way for an application to cancel the reload operation of a Shard Cluster. Cancel PeriodKey If set to true, the reload operation of the shard cluster will be aborted Internal use only Remarks During the AutoRefresh operation of a Shard Cluster object the OnClusterDefinitionChanged event is raised to warn the application that the Shard Cluster is about to be reloaded. When implementing the associated delegate the application code can decide to cancel the reload operation. Example // This code assumes you have created a Cluster called MYCLUSTER with a Default shard // Note: replace the connection string with valid values string connectionstring = "Data Source=myserver.database.windows.net;Initial Catalog=DB1;UID=myuserid; PWD=123456"; ShardCluster sc = new ShardCluster(connectionString, "MYCLUSTER"); sc.onclusterdefinitionchanged += new ShardCluster.ClusterDefinitionChangedDelegate(sc_OnClusterDefinitionChanged);... void sc_onclusterdefinitionchanged(shardcluster.eventresult e) { // Cancel the event e.cancel = true; } Copyright (C) Blue Syntax Consulting Page 19