Michiel Wories' WebLog : SMO Samples

SMO Samples Galore

mwories — Tue, 25 Oct 2005 19:47:00 GMT

With much of the SQL Server 2005 devcelopment behind us, I am starting to have some more time to post some SMO samples. Most of these are inspired on questions in the beta newsgroups or the SMO/DMO forum.

Additionally, SQL Server 2005 ships with a pretty wide variety of samples. In fact, there are more SMO samples than there are for any other product area, and we have been adding samples up till a a few weeks ago (from here it is pretty much locked down).

Let me know if you have any sample requests!

SQL Server: Table Partitioning in SQL Server 2005

mwories — Fri, 24 Jun 2005 22:07:00 GMT

Table and Index partitioning is one if the new SQL Server 2005 features that willl improve life for the DBA and application developer quite a bit. It allows Indexes and Tables to be partitioned across multiple file groups. Partitioned tables and indexes, are fully manageable with SMO. Here is a quick sample to get you started, with not too much explanation as speaks for itself, mostly. Let me know if you have questions!

Server svr = new Server();

Database db = new Database(svr, "MyDatabase");
db.FileGroups.Add(new FileGroup(db, "PRIMARY"));
db.FileGroups.Add(new FileGroup(db, "SECONDARY"));
db.FileGroups[0].Files.Add(new DataFile(db.FileGroups[0], "datafile1", @"c:\db1.mdf"));
db.FileGroups[1].Files.Add(new DataFile(db.FileGroups[1], "datafile2", @"c:\db2.mdf"));
db.Create();

PartitionFunction pf = new PartitionFunction(db, "MyPartitionFunction");
pf.PartitionFunctionParameters.Add(new PartitionFunctionParameter(pf, DataType.Int));
pf.RangeType = RangeType.Left;
pf.RangeValues = new object[] { 5000 };
pf.Create();

PartitionScheme ps = new PartitionScheme(db, "MyPartitionScheme");
ps.PartitionFunction = "MyPartitionFunction";
ps.FileGroups.Add("PRIMARY");
ps.FileGroups.Add("SECONDARY");
ps.Create();

Table t = new Table(db, "MyTable");
t.Columns.Add(new Column(t, "c1", DataType.Int));
t.Columns.Add(new Column(t, "c2", DataType.VarChar(100)));
t.PartitionScheme = "MyPartitionScheme";
t.PartitionSchemeParameters.Add(new PartitionSchemeParameter(t, "c1"));
t.Create();

// Script out the objects (for educational purposes; optional)
SqlSmoObject[] objs = new SqlSmoObject[4];
objs[0] = db;
objs[1] = pf;
objs[2] = ps;
objs[3] = t;

for (int i = 0; i < 4; i++)
{
    Console.WriteLine("-- " + objs[i].ToString());
    foreach (string s in ((IScriptable)(objs[i])).Script())
    {
        Console.WriteLine(s);
    }
    Console.WriteLine("GO");
}

SQL Server: Capture Object changes with SMO Capture Mode

mwories — Wed, 01 Jun 2005 00:51:00 GMT

In a previous article I have showed how a SMO object can be serialized into a Transact-SQL script, which allows you to recreate the object. What if you want to have the script that is emitted when you changed one or more properties of an object? In that case Capture Mode comes in handy. This switches the ServerConnection object in a state where it starts capturing all statements that SMO emits instead of sending these to the server. The following sample illustrates how it is used.

Server svr = new Server();

Database db = svr.Databases["MySmoTestDatabase"];

// First create new test database, if it does not exist
if (db == null)
{
    db = new Database(svr, "MySmoTestDatabase");
    db.Create();
}

// Set an option (we flip it to on or off depending orginal state)
db.DatabaseOptions.AutoClose = !db.DatabaseOptions.AutoClose;

// Switch SMO in capture mode
svr.ConnectionContext.SqlExecutionModes = SqlExecutionModes.CaptureSql;

// Now perform the operation
db.Alter();

// Don't forget to switch back
svr.ConnectionContext.SqlExecutionModes = SqlExecutionModes.ExecuteSql;

// Put database back in original state
db.Refresh();

// Print script
foreach (string s in svr.ConnectionContext.CapturedSql.Text)

{
    Console.WriteLine(s);
}

Note the Refresh() near the end. This is needed to bring back the Database object in sync with the server again. It’s not enough to execute the script (if you would do that) to bring it in sync with the server.

SQL Server: SMO Scripting Basics

mwories — Sat, 07 May 2005 21:51:00 GMT

Let's first clarify what I mean by "scripting". It often happens during talks or when I explain SMO fundamentals that eyes gloss over, shortly after which the "what * do you mean by scripting" question pops up (replace the * with your favorite combination of adjective and noun to indicate bewilderment). For people who, unlike me, do not live their lives in SQL land, "scripting" means typically some kind of language script, like perl, VBScript, or others, that allows you, without the use of a development environment to author and execute code". Not so in this case. If I were to be precise, it means "serialize a SMO or DMO object into Transact-SQL". So now we have this out of the way, let's take a look at SMO Scripting.

SMO objects, when either just instantiated and not yet persisted, or just retrieved from the server, carry state. For example a StoredProcedure object has a name, a schema, a text body, and maybe some other optional properties. This state can be serialized into a Transact-SQL script that you may store, modify, or execute. As SQL Server’s primary language is Transact-SQL, it’s obvious that one of the tasks that the SMO object model has to perform very well is scripting. SMO objects can be scripted in 5 different ways:

By calling the Script() method on the object.
By instantiating a Scripter object, and pass in a reference of the object(s) to be scripted.
Advanced scripting: generating a script in 3 distinct phases (discovery, list, script)
By using the Transfer object.
Indirectly, by capturing the SQL output of the objects

I will discuss 1 and 2 and will dedicate some more posts on the other more advanced topics.

Basic Scripting

Let’s start with scripting an existing object, with no options specified (installing AdventureWorks will help running these samples):

Server svr = new Server();

foreach (string s in svr.Databases["AdventureWorks"].StoredProcedures["uspGetEmployeeManagers", "dbo"].Script())
{
      Console.WriteLine(s);
}

If you run this code, the script should be emitted to the console. So far pretty straightforward eh?

Scripting Options

If you want to do more than just scripting the object, there are scripting options that you can pass into the Script() method. There 2 ways to pass in Scripting options. The following 2 samples illustrate the different methods of passing in scripting options.

Server svr = new Server();

StoredProcedure sp = svr.Databases["AdventureWorks"].StoredProcedures["uspGetEmployeeManagers", "dbo"];

ScriptingOptions so = new ScriptingOptions();

so.IncludeHeaders = true;

so.SchemaQualify = true;

foreach (string s in sp.Script(so))

      Console.WriteLine(s);

In the next sample, you use the ScriptOption class. This class has various static members that each return an instance of a ScriptionOption class.

Server svr = new Server();

StoredProcedure sp = svr.Databases["AdventureWorks"].StoredProcedures["uspGetEmployeeManagers", "dbo"];

foreach (string s in sp.Script(ScriptOption.IncludeHeaders + ScriptOption.SchemaQualify))

      Console.WriteLine(s);

You can take advantage of the fact that the ScriptOption static members returns a ScriptingOption class (through implict conversion), as you can use it as an alternative to construct a Scriptingoption class:

ScriptingOptions so = ScriptOption.IncludeHeaders;

so.SchemaQualify = true;

Script modified objects

You can modify and script an object, without persisting its state. This sample shows how this can be accomplished:

Server svr = new Server();

StoredProcedure sp = svr.Databases["AdventureWorks"].StoredProcedures["uspGetEmployeeManagers", "dbo"];

sp.TextHeader = "-- Scripted at " + DateTime.Now.ToString() + "\n\n" + sp.TextHeader;

foreach (string s in sp.Script())
{
      Console.WriteLine(s);
}

Ensure that you either call the Refresh() method on the object once you are done, or persist the object by calling Alter(), as this temporary state may cause problems when this object is referenced again for other purposes.

Script non-existing objects

Alternative, you can instantiate a new object, and emit the script for it, without requiring it to exist on the server. In fact the below script will not even connect to the server; this happens all on your client.

Server svr = new Server();

Database db = new Database(svr, "MyDatabase");

db.DatabaseOptions.AutoClose = true;

foreach (string s in db.Script())
{

Console.WriteLine(s);
}

Using the Scripter object

If you call the Script() method on an object, what actually happens, is that in the background a Scripter() object is instantiated, which performs the various scripting operations. Whereas each object knows how to emit script, the Scripter object pulls it all together, and does special processing before or while generating the output. Let’s take a look how the Scripter object can be used to accomplish the same task as above (scripting a database).

Server svr = new Server();

Database db = new Database(svr, "MyDatabase");

db.DatabaseOptions.AutoClose = true;

Scripter scripter = new Scripter();

scripter.Server = svr;

scripter.Options.IncludeHeaders = true;

scripter.Options.SchemaQualify = true;

SqlSmoObject[] objs = new SqlSmoObject[1];

objs[0] = db;

scripter.Script(objs);

foreach (string s in scripter.Script(objs))

      Console.WriteLine(s);

The above samples I have touched on the basis of the scripting operations. In the next posts I will elaborate and show you more complex and elaborate ways to generate script. We made scripting extremely flexible, and hope that this first post helps you to get started with scripting.

Enjoy!

SQL Server: Tuning your SMO Application for great performance -- PART 2

mwories — Mon, 02 May 2005 11:21:00 GMT

In the previous post I provided you with a fundamental tool to minimize the amount of SQL statements emitted and therefore limit expensive network round-trips (and SQL statements) using the Server.SetDefaultInitFields() method. In this post I will provide you with some more detail about this method, alongside with a recommendation about its use.

Let's take a quick look at the optimized sample that I provided last article:

Server svr = new Server();

Database db = svr.Databases["AdventureWorks"];
svr.SetDefaultInitFields(typeof(Table), "CreateDate");
foreach (Table t in db.Tables)
{
Console.WriteLine(t.Schema + "." + t.Name + " " + t.CreateDate);
}

This optimization is particular to this piece of code, but the setting is global to the Server instance so every time you will retrieve a Table object later in your code, it will load the same fields as just specified. It's recommended to save the state of the previous SetDefaultInitFields setting so you can set it to the same value after you have retrieved your objects. The following sample shows you have to save the state, and then set if back to that state:

Server svr = new Server();

Database db = svr.Databases["AdventureWorks"];

StringCollection sc = svr.GetDefaultInitFields(typeof(Table));

svr.SetDefaultInitFields(typeof(Table), "CreateDate");
foreach (Table t in db.Tables)
{
Console.WriteLine(t.Schema + "." + t.Name + " " + t.CreateDate);
}
svr.SetDefaultInitFields(typeof(Table), sc);

The reason you want to be careful with this is that the SetDefaultInitFields setting is global to the Server object reference, and you are likely to hold on to the Server object instance reference (svr in the above example) to perform additional work with it. For example, if you were to call Refresh() on the Tables collection, any additional operation that would cause a table object to be instantiated in the collection will use the latest SetDefaultInitFields setting.

SetDefaultInitFields has a few more helpful overloads that I will describe here:

SetDefaultInitFields(System.Type typeObject, System.Boolean allFields)	Specifies all properties are fetched when the specified object is instantiated. When set to false, the fields will be reset to default.
SetDefaultInitFields(System.Boolean allFields)	Specifies all properties are fetched when any object is instantiated. When set to false, the fields will be reset to default..

Recommendation: make sure your application is aware of this global Server state, and either specifically set the fields or reset to the previous value. If you do not take care about this, you may see sudden application degradation (or your customers may start to notice), and as it will be very hard to test all code paths you cannot know beforehand how your application is going to behave in the future if· this is not carefully managed. Also, if you pass the Server reference on to another library that component may change the field settings and cause 'mysterious' performance degradation that may be hard to debug.

SQL Server: Tuning your SMO Application for great performance - PART 1 (featured at TechED)

mwories — Fri, 22 Apr 2005 23:16:00 GMT

I'm ramping up for TechED 2005 (Both USA and Europe) and will be giving a couple of talks on SMO. This is a repost of an article from SqlJunkies, as I am still moving these blog entries to MSDN. Ping me if you are visiting TechED and are interested in certain SMO topics.

Unlike SQL-DMO, SQL Server Management Objects (SMO) gives you a fairly fine level of control how data is retrieved from the server.

When using default behavior, an SMO object transitions into the following states:

1. Partially instantiated -- some properties are available (such as Name, Schema)
2. Fully instantiated -- all low cost properties are retrieved in bulk when you retrieve any of these
3. Expensive properties -- are fetched when needed, one at the time (such as database space)

The rationale behind this is to allow the object model to scale when a high number of objects need to be retrieved, for example when populating a collection of 10,000 tables. In contrast, SQL-DMO always fetches all properties when populating a collection. This can be compared with doing a 'select * from xxx', when you only want to know something about name and the creation date of the object. SMO fetches only the minimal set of properties that are required to populate the collection (i.e. for Table, Name and Schema are needed to uniquely identify the object).

Now here comes the catch: if your application does fetch extra properties, besides the minimally required ones, it will submit a query to retrieve these extra properties. This can cause your application to become extremely 'chatty', and will likely cause it to perform not as good (or just bluntly bad). This is especially noticed when doing 'foreach' enumerations, such as shown in the example below:

Server svr = new Server();

Database db = svr.Databases["AdventureWorks"];
foreach (Table t in db.Tables)
{
Console.WriteLine(t.Schema + "." + t.Name + " " + t.CreateDate);
}

You can inspect the result by switching SQL Profiler on and looking at the number of batches that are emitted to SQL Server.

When running above sample you will find about 155 rows in the SQL Profiler. The application is certainly chattier than it should be. This app's performance is especially down the drain on networks with a higher latency than a typical LAN, but even on a LAN it does not perform very well.

Enter Server.SetDefaultInitFields(). This call allows you to set the fields that are retrieved when the object gets initialized. This would add one extra line to the above sample:

Server svr = new Server();

Database db = svr.Databases["AdventureWorks"];
svr.SetDefaultInitFields(typeof(Table), "CreateDate");
foreach (Table t in db.Tables)
{
Console.WriteLine(t.Schema + "." + t.Name + " " + t.CreateDate);
}

Note that you do not have to indicate any of fields that are retrieved by default (Name, Schema).

After running the above sample, you will find only 11 rows in SQL Profiler, and you will also notice that the first sample you could see it fill the screen line by line (I'm running this on a 1.8Ghz P4 Toshiba notebook with 1Gb of memory) and the optimized sample flashes by and disappears in a split second (could have added some timing to the sample, but for clarity I keeping it as short as possible.

The bottom line is that you need to understand your application behavior and tuning will make a big difference. With more options to tune SMO, the responsibility to tune your application has shifted to you, as SMO cannot guess what your application is going to request. "With great power comes great responsibility" :-)

Next post will be on some of the more advanced tuning options SMO has to offer. If you have a special request about what you like me post on in the SMO space (or SQL-DMO, SQLCMD, OSQL, SQL WMI Provider, SQL Computer Manager, or XP's for that matter), then let me know.

Michiel Wories (a PM on the SQL Server Team)
---
See also: http://staff.develop.com/bobb/weblog/PermaLink.aspx?guid=0c070aff-a30f-4669-b0ae-ef7a2cde81c6
---
This posting is provided "AS IS" with no warranties, and confers no rights.