How To Use The New Persistent Dictionary Features

Download the beta release of the PersistentDictionary here: Attach:oct12.zip Note that this WILL be superceeded by the GT shared dictionary, when it is finished.

There is a new version of the Shared Dictionary that makes use of a SQL server to provide the capacity for persistent entries. However, to make use of these new features, there is a mild cost in terms of added complexity to the system.

To use the persistent features of the Shared Dictionary, you'll need to have access to an SQL server. See VisualStudio.SQLAndC#SQL for information on starting an SQL server. You'll need to add a table to the database you intend to connect to via this command:

create table shareddata (PathName varchar(max), BinaryValue image)

Next, you'll need to actually connect the shared dictionary to the server. To do this, you'll need to call the ConnectToSQLServer(String ConnectionInfo) on an instance of a Shared Dictionary. The ConnectionInfo string is in precisely the same format as the one explained in VisualStudio.SQLAndC#Connect. Once this has been done, the Shared Dictionary is connected and ready to use the persistent features.

First of all, you can load stored values back into the dictionary by calling the shared dictionary method LoadStoredValues() on an instance of Shared Dictionary.

To close the SQL connection, you can simply call DisconnectFromSqlServer(). This will prevent you from being to use any persistence features until a new SQL connection is created.

By default, no entry is stored in the SQL database for future use. Instead, we introduce a new metadata tag to tell the shared dictionary to store the value.

We do this via the ".persistent" attribute. When you set an entry's .persistent tag equal to "now", the entry, along with any attributes, is immediately stored within the SQL server. This save is done once, no further updates are performed until the .persistent attribute is set again.

e.g. this.SD["/message1.persistent"] = "now";

If its .persistent attribute is set to "always" the entry and all its attributes are immediately saved to the SQL server, and any further changes will immediately be saved. Over the course of its lifetime, an entry may change between having a .persistent tag set to "now" and "always" as necessary.

e.g. this.SD["/message1.persistent"] = "always";

To remove an entry from the SQL server (but not from the shared dictionary), simply remove the .persistent tag from that entry.

e.g. this.SD.Remove("/message1.persistent");

Why not universally set the .persistent attribute to "always"? The SQL server is slow, and the cost of storing a value that changes on a regular basis may become a bottleneck. Some simple, but demonstrative statistics:

1000 inserts of an integer

1000 inserts of 128Kb

1000 inserts of 1Mb