439 CHAPTER 12 Developing with SMO IN THIS CHAPTER Using SMO SMO Hierarchy Building the SMO Sample Application Copyright © 2006 by The McGraw-Hill Companies. Click here for terms of use. 440 Microsoft SQL Server 2005 Developer’s Guide I n this chapter, you learn how you can manage SQL Server programmatically from VB.NET by taking advantage of SQL Management Objects (SMO). Like its predecessor, Distributed Management Objects (SQL-DMO), SMO enables you to develop custom SQL Server management applications that you can tailor to your environment. Using SMO with VB.NET or any other .Net language, you can create custom SQL Server management interfaces that let you perform all the functions SQL Server’s Management Studio provides. In fact, SMO is the foundation for SQL Server’s Management Studio. Using SMO, you can list databases and tables; add logins; control replication; import and export data; and perform backups, restores, and many other administrative tasks. SMO opens up SQL Server to a number of custom programs that can both display and manipulate SQL Server and all of its databases and objects. In this chapter, you get an overview of SMO, as well as a look at its underlying architecture. Then, you see how to use SMO from VB.NET. In this section, you see how to add the SMO object library to the Visual Basic Integrated Development Environment (IDE). You also see how to perform some common tasks with SMO. Finally, this chapter finishes by presenting a sample SQL Server management utility that’s built using VB.NET and SMO. Using SMO To get programmatic access to management functions of other database platforms, you might need to master low-level networking and system interfaces—if it’s available at all. However, SMO provides a .NET framework solution that makes SQL Server’s database management functions easy to access. The hierarchy for the SMO objects used in the .NET framework is discussed in the next section of this chapter. SQL Server’s SMO functions can be used by a programming language that is supported by the Common Language Runtime (CLR), such as Visual Basic.NET and Visual C#.NET. To use SMO from VB.NET, follow these basic steps: 1. Add a reference to the SMO assemblies and then import the namespaces that are required so that your program can recognize the SMO types. 2. Create an instance of the Server object. 3. Establish a connection to the instance of the Server object to SQL Server. 4. Use the Server object. 5. Disconnect from SQL Server. Chapter 12: Developing with SMO 441 The following section of the chapter walks you through the basic steps needed to build a project using SMO. The project presented is a Winforms project built in Visual Basic, but you can follow these steps to build an ASP project or even a command-line project. Adding SMO Objects to Visual Studio Before you can begin to use the SMO objects in Visual Basic’s development environment, you need to incorporate the SMO assemblies into your Visual Basic project. The files that provide the basic support for SMO are copied to your client system when you first install the SQL Server client. However, you still need to set a reference to them in Visual Studio’s development environment to enable their use from your applications. To add the SMO references to your Visual Studio project, you must select the Add Reference option from the Project menu. This action displays the References dialog box you can see in Figure 12-1. Select the .NET tab and scroll through the References dialog box until you see the SMO assemblies: Microsoft.SqlServer.ConnectionInfo, Microsoft.SqlServer .Smo, Microsoft.SqlServer.SmoEnum, and Microsoft.SqlServer.SqlEnum. Selecting these items and then clicking OK adds the references to Visual Basic’s Interactive Figure 12-1 Adding references to SMO 442 Microsoft SQL Server 2005 Developer’s Guide Development Environment (IDE). To see the SMO properties and methods, you must use Visual Basic’s Object Browser, shown in Figure 12-2. Creating the Server Object Before you can use any of the SMO methods, you must first specify an import directive for the Microsoft.SqlServer.Management.Smo Namespace in your project. The Microsoft.SqlServer.Management.Smo Namespace contains all of the related SQL Server connection and data access classes. To add an import directive for the Microsoft.SqlServer.Management.Smo to a VB.NET project, you would add the following code to the declaration section of your source file: Imports Microsoft.SqlServer.Management.Smo Next, you must create an instance of the Server object, which is the most basic object in the SMO set. You can create an instance of the Server object and establish a connection to the SQL Server instance in three different ways: explicitly setting Figure 12-2 Viewing an SMO assembly from the Object Browser Chapter 12: Developing with SMO 443 the connection information through the Server object properties, passing the SQL Server instance name to the Server object constructor function, or using the ServerConnection object to provide the connection information. To explicitly set the connection information through the Server object properties, you simply declare the Server object variable using the default constructor. If you do not set any of the Server object’s properties, the Server object attempts to connect to the local instance of SQL Server with the default connection settings. To connect to a remote or named instance of SQL Server, set the name property and any other properties that affect the connection settings, such as authentication mode, logins, and passwords, as shown here: Dim oSQLServer As New Server() oSQLServer.ConnectionContext.LoginSecure = false oSQLServer.ConnectionContext.Login = "username" oSQLServer.ConnectionContext.Password = "password" To pass the SQL Server instance name to the Server object, you first declare the Server object variable and pass the SQL Server instance name as a string parameter in the constructor, as shown here: Dim oSQLServer As Server = New Server("SQL2005") To use the ServerConnection object, you need to specify an import directive for the Microsoft.SqlServer.Management.Common namespace. The import directive for Microsoft.SqlServer.Management.Common is added to the declaration section of your source file: Imports Microsoft.SqlServer.Management.Common In order to use the ServerConnection object to provide the connection information to the Server object, you declare a ServerConnection object variable and set the connection information, such as the SQL Server instance name and the authentication mode into its properties. You then pass the ServerConnection object as a parameter to the Server object constructor. Here is an example of this method: Dim oServerConn As ServerConnection = New ServerConnection() oServerConn.ServerInstance = "SQL2005" oServerConn.LoginSecure = True Dim oSQLServer As New Server(oServerConn) 444 Microsoft SQL Server 2005 Developer’s Guide NOTE One advantage to using the ServerConnection object is that the connection information can be reused. SMO removes the association between the application object and the Server object, allowing you to release the application state. In other words, you can instantiate a Server object by reusing an existing connection, perform your application processes, and then release the reference to the Server object. This lets you write a program that use memory efficiently by controlling when you want to release an object’s state. Using SMO Properties A SQLServer object has more than 1000 different properties that can be accessed from your application. The SMO hierarchy section later in this chapter will show some of the most common SMO objects. The SQL Server Books Online help file lists all the SMO object properties and notes whether they are read-only or read/write. TIP You can use the Object Browser to list the properties for each SQLServer object from Visual Studio’s IDE. Getting Property Values You can retrieve the property values for all the properties that are standard data types using the Visual Basic assignment operator (“=”), as shown here: Dim sInstanceName As String sInstanceName = oSQLServer.InstanceName Here, you can see that a string named sInstanceName is first declared using the Visual Basic Dim statement. Then the Visual Basic assignment operator is used to fill the sInstanceName string variable with the contents of the oSQLServer .InstanceName property. This technique works for all the standard Visual Basic data types, including String, Long, and Integer. Object properties are treated a little differently, however, as you can see in following example: Dim oJobServer As Microsoft.SqlServer.Management.Smo.Agent.JobServer oJobServer = oSQLServer.JobServer To retrieve the contents of SMO object properties, you assign an object reference to a variable. In this case, the Dim statement is used to declare an object of the Smo .Agent.JobServer data type named oJobServer. Then you assign the contents of the oSQLServer.JobServer object to the oJobServer object. Chapter 12: Developing with SMO 445 Setting Property Values You can set the value of SMO read/write properties from Visual Basic by using the assignment operator (“=”). The following example shows how to set the SQLServer object’s ApplicationName property: Dim boolDefaultTextMode As Boolean boolDefaultTextMode = True oSQLServer.DefaultTextMode = boolDefaultTextMode In this example, you can see the oSQLServer.DefaultTextMode property is set using the Visual Basic assignment operator to the value of “True”, which is contained in the boolDefaultTextMode Boolean variable. TIP While you can set only properties that use standard data types—such as String, Boolean, or Long—you cannot set any of the SMO properties that are object data types. Object properties are always read-only. SMO Property Collections SMO’s core object hierarchy makes extensive use of object collections, which are basically groups of related objects. For instance, the Databases collection in the Server object is a collection of Database objects. TIP Collection objects typically end with an s. For instance, Databases indicates a collection of Database objects. Table 12-1 lists the object collections that are part of the Server object. Like objects, collections are all contained within a parent object. In the case of the object collections shown in Table 12-1, all the object collections belong to the SQLServer core object. A collection object is actually an object that has its own set of properties and methods. The following list shows the different properties and methods contained in the Databases collection: Count property IsSynchronized property Item property 446 Microsoft SQL Server 2005 Developer’s Guide ItemByID method Parent property Refresh method You can see that the properties and methods of the Databases collection objects are all oriented toward working with the group of databases. For instance, the Count property reports on the number of Database objects contained in the collection, while the ItemByID method returns a specific Database object in the Databases collections. Because all collection objects contain and manage multiple objects, the properties and methods for all collections are similar. In contrast, the following list shows a selection of some of the primary properties of an individual Database object: CreateDate property DataSpaceUsage property Defaults collection Drop method FileGroups collection Table 12-1 SMO Server Object Collections SMO Server Object Collection Description BackupDevices Listing of backup devices available Credentials Listing of credential objects Databases Listing of databases Endpoints Listing of endpoints defined Languages Listing of supported languages LinkedServers Listing of registered linked servers Logins Listing of login IDs Roles Listing of roles defined on SQL Server SystemDataTypes Listing of system data types defined SystemMessages Listing of system messages Triggers Listing of triggers defined UserDefinedMessages Listing of user-defined messages Chapter 12: Developing with SMO 447 Name property Owner property Rename method SpaceAvailable property StoredProcedures collection Tables collection Views collection You can see that the properties and methods of the Database object are all directly related to a SQL Server database. For instance, the Drop method drops the database from the server, while the Owner property contains the name of the database owner. Notice that some of the Database object properties are also other Collection objects. For instance, the StoredProcedures property is a collection of the stored procedures in the database. Likewise, the Tables property is a collection of the tables contained in the database. Iterating Through Collections To use SMO effectively, one of the first things you should know is how to work with the collection objects. Iterating through a collection can be accomplished using the following code: Dim oServerConn As ServerConnection = New ServerConnection() oServerConn.ServerInstance = "SQL2005" oServerConn.LoginSecure = True Dim oSQLServer As New Server(oServerConn) For Each oDatabase As Database In oSQLServer.Databases Debug.Print (oDatabase.Name) Next Visual Basic’s For Each statement automatically loops through all the objects in a collection. This example prints a list of all the database names contained in the Databases collection of the oSQLServer object. The code within the For Each block refers to the current object in the collection. Getting a Specific Collection Object You also need to understand how to reference a specific object in a collection. You can refer to individual objects within a collection either by the object name or by 448 Microsoft SQL Server 2005 Developer’s Guide the ordinal value within the collection. For example, to refer to a Database object by name, you could use the following: Dim oServerConn As ServerConnection = New ServerConnection() oServerConn.ServerInstance = "SQL2005" oServerConn.LoginSecure = True Dim oSQLServer As New Server(oServerConn) oSQLServer.Databases("SMOSample") or Dim oServerConn As ServerConnection = New ServerConnection() oServerConn.ServerInstance = "SQL2005" oServerConn.LoginSecure = True Dim oSQLServer As New Server(oServerConn) oSQLServer.Databases.Item("SMOSample") or Dim oServerConn As ServerConnection = New ServerConnection() oServerConn.ServerInstance = "SQL2005" oServerConn.LoginSecure = True Dim oSQLServer As New Server(oServerConn) Dim sDatabaseName As String sDatabaseName = "SMOSample" oSQLServer.Databases.Item(sDatabaseName) All these examples are equivalent. In each case, they reference the database named “SMOSample” in the oSQLServer object. Because the Item method is the default, you can optionally omit the use of the “Item” method. In other words, to reference an individual collection object by name, you pass the Item method a string containing the object’s name. NOTE This code implicitly uses the Item method of the collection object. The Item method is the default method in a collection; therefore, you needn’t explicitly code oSQLServer.Databases.Item(“SMOSample”). The Item method can accept either a string or an ordinal number. . Server( oServerConn) oSQLServer.Databases("SMOSample") or Dim oServerConn As ServerConnection = New ServerConnection() oServerConn.ServerInstance = " ;SQL2 005" oServerConn.LoginSecure = True Dim oSQLServer As New Server( oServerConn) oSQLServer.Databases.Item("SMOSample") or Dim. ServerConnection() oServerConn.ServerInstance = " ;SQL2 005" oServerConn.LoginSecure = True Dim oSQLServer As New Server( oServerConn) 444 Microsoft SQL Server 2005 Developer’s Guide NOTE One advantage to using the ServerConnection. box until you see the SMO assemblies: Microsoft. SqlServer.ConnectionInfo, Microsoft. SqlServer .Smo, Microsoft. SqlServer.SmoEnum, and Microsoft. SqlServer.SqlEnum. Selecting these items and then