---

A workspace is a container of spatial and nonspatial datasets, such as feature classes, raster datasets, and tables. Workspaces provide methods to instantiate existing datasets and to create datasets. The following are the three types of workspaces:

To create a workspace, first create an appropriate workspace factory. Each workspace type has its own workspace factory. A workspace factory is a dispenser of workspaces and allows a client to create a workspace specified by the directory, file name, and/or connection properties. A workspace factory is a co-creatable singleton object (see Interacting with singleton objects). A singleton object can only be instantiated once in a process. The workspace factory classes for geodatabase workspaces are found in the DataSourcesGDB library, while those for the non-geodatabase workspaces mentioned in this topic are found in the DataSourcesFile library.

The Create method can be used to create a file system workspace or local geodatabase, or to create a connection file to an ArcSDE geodatabase. The connectionProperties parameter specifies any additional connection properties needed for ArcSDE geodatabases, such as the server, instance, and so on.

When a connection file to an ArcSDE geodatabase is being created—if no connection properties are specified—a dialog box appears prompting the user for the required properties. The hWnd parameter gives the Create method a handle to a parent window. Typically, a value of 0 can be used.

The Create method returns an IWorkspaceName reference that can be used to open or return certain information about the workspace. The Create method cannot be used to create geodatabases in an enterprise, personal, or workgroup ArcSDE (see Creating a geodatabase in a personal or workgroup ArcSDE workspace in this topic).

Activator.CreateInstance vs. New—The examples in this topic instantiate workspace factories using the Activator.CreateInstance method rather than the new keyword. This is because workspace factories are singleton Component Object Model (COM) classes. For more information, see Interacting with singleton objects. 

The required workspace factory to create a file geodatabase is a FileGDBWorkspaceFactory. The following code example creates a file geodatabase in the specified directory with the supplied name. The connectionProperties parameter is null as it is not required for the creation of a personal geodatabase.

public static IWorkspace CreateFileGdbWorkspace(String path)
{// Instantiate a file geodatabase workspace factory and create a file geodatabase.// The Create method returns a workspace name object.Type factoryType = Type.GetTypeFromProgID("esriDataSourcesGDB.FileGDBWorkspaceFactory");IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance(factoryType);IWorkspaceName workspaceName = workspaceFactory.Create(path, "Sample.gdb", null,0);// Cast the workspace name object to the IName interface and open the workspace.IName name = (IName)workspaceName;IWorkspace workspace = (IWorkspace)name.Open();return workspace;
}

The required workspace factory to create a personal geodatabase is an AccessWorkspaceFactory. The following code example creates a personal geodatabase in the specified directory with the supplied name. The connectionProperties parameter is null as it is not required for the creation of a personal geodatabase.

public static IWorkspace CreateAccessWorkspace(String path)
{// Instantiate an Access workspace factory and create a personal geodatabase.// The Create method returns a workspace name object.Type factoryType = Type.GetTypeFromProgID("esriDataSourcesGDB.AccessWorkspaceFactory");IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance(factoryType);IWorkspaceName workspaceName = workspaceFactory.Create(path, "Sample.mdb", null,0);// Cast the workspace name object to the IName interface and open the workspace.IName name = (IName)workspaceName;IWorkspace workspace = (IWorkspace)name.Open();return workspace;
}

When invoked on an ArcSDE workspace factory, the Create method does not create a geodatabase; instead, it creates an ArcSDE connection file.

The following are the two different procedures used to create an ArcSDE geodatabase:

ArcSDE enterprise geodatabases are stored using separate database management system (DBMS) products. Therefore, before creating the ArcSDE geodatabase system tables and your data tables, set up the underlying DBMS. The specifics of this vary based on the type of DBMS being used.

The following code example shows how to use the Create method to make an ArcSDE connection file to an ArcSDE geodatabase:

public static IWorkspaceName CreateConnectionFile(String path, String server, Stringinstance, String user, String password, String database, String version)
{IPropertySet propertySet = new PropertySetClass();propertySet.SetProperty("SERVER", server);propertySet.SetProperty("INSTANCE", instance);propertySet.SetProperty("DATABASE", database);propertySet.SetProperty("USER", user);propertySet.SetProperty("PASSWORD", password);propertySet.SetProperty("VERSION", version);Type factoryType = Type.GetTypeFromProgID("esriDataSourcesGDB.SdeWorkspaceFactory");IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance(factoryType);return workspaceFactory.Create(path, "Sample.sde", propertySet, 0);
}

The DataServerManager is used to access and administer one or more geodatabases stored on a data server. A connection can also be opened to each geodatabase in a data server by using the IWorkspaceName and IName interfaces. The following code example shows how to create a geodatabase in a personal or workgroup ArcSDE using the DataServerManager.

Creating a geodatabase in a personal or workgroup ArcSDE creates databases on an SQL Server Express database instance. Only database server administrators can create ArcSDE personal or workgroup geodatabases.

// dataServerName parameter should be in "<machine_name>\\<sql_instance>" format.
public static void CreatePersonalOrWorkgroupArcSdeWorkspace(String dataServerName)
{// Create a data server manager object.IDataServerManager dataServerManager = new DataServerManagerClass();// Set the server name and connect to the server.dataServerManager.ServerName = dataServerName;dataServerManager.Connect();// Cast to the admin interface, check permissions, and create the geodatabase.IDataServerManagerAdmin dataServerManagerAdmin = (IDataServerManagerAdmin)dataServerManager;if (dataServerManagerAdmin.IsConnectedUserAdministrator){dataServerManagerAdmin.CreateGeodatabase("LandUse", @"C:\Temp\LandUse.mdf",0, "", 0);// Create a Name object to open the workspace.IWorkspaceName workspaceName = dataServerManagerAdmin.CreateWorkspaceName("LandUse", "VERSION", "dbo.Default");IName name = (IName)workspaceName;IWorkspace workspace = (IWorkspace)name.Open();}
}

The ScratchWorkspaceFactory and FileGDBScratchWorkspaceFactory classes are used to connect to a temporary file or personal geodatabase known as a scratch workspace. These workspaces are commonly used to store intermediate results in operations that require several steps. These factories are fundamentally different from the FileGDBWorkspaceFactory and AccessWorkspaceFactory classes for the following two reasons:

The two types of scratch workspace factories are used in a similar manner, but scratch workspaces created as file geodatabases can take advantage of their cross-platform characteristics and can handle larger amounts of data.

Scratch workspace factories maintain a "default" scratch workspace. The first time the default scratch workspace is requested, a scratch workspace will be created and returned. Subsequent requests within the same session returns the same scratch workspace.

The following code example shows how to request the default scratch workspace:

public static IWorkspace OpenScratchWorkspace()
{// Create a scratch workspace factory.Type factoryType = Type.GetTypeFromProgID("esriDataSourcesGDB.ScratchWorkspaceFactory");IScratchWorkspaceFactory scratchWorkspaceFactory = (IScratchWorkspaceFactory)Activator.CreateInstance(factoryType);// Get the default scratch workspace.IWorkspace scratchWorkspace = scratchWorkspaceFactory.DefaultScratchWorkspace;return scratchWorkspace;
}

The following code example shows how to get the default scratch workspace based on a file geodatabase:

public static IWorkspace OpenFileGdbScratchWorkspace()
{// Create a file scratch workspace factory.Type factoryType = Type.GetTypeFromProgID("esriDataSourcesGDB.FileGDBScratchWorkspaceFactory");IScratchWorkspaceFactory scratchWorkspaceFactory = (IScratchWorkspaceFactory)Activator.CreateInstance(factoryType);// Get the default scratch workspace.IWorkspace scratchWorkspace = scratchWorkspaceFactory.DefaultScratchWorkspace;return scratchWorkspace;
}

Connecting to a geodatabase

SummaryThis topic demonstrates how to connect to each type of geodatabase. It also shows how to connect to a transactional or historical version of an ArcSDE geodatabase.

In this topic

• About workspaces
  • Methods for connecting to a workspace
• Connecting to file geodatabases
• Connecting to personal geodatabases
• Connecting to enterprise ArcSDE geodatabases
  • Connecting to a transactional version
  • Connecting to a historical marker name
  • Connecting to a historical time stamp
• Connecting to personal and workgroup ArcSDE geodatabases
  • Using the workspace factory
  • Using the DataServerManager

About workspaces

• Shapefile workspaces and ArcInfo workspaces are examples of file-based workspaces (esriFileSystemWorkspace).
• Personal and file geodatabases are examples of local database workspaces (esriLocalDatabaseWorkspace).
• An ArcSDE geodatabase stored in a relational database management system (RDBMS) such as Oracle, DB2, Structured Query Language (SQL) Server, Informix or PostgreSQL is a remote database workspace (esriRemoteDatabaseWorkspace).

Methods for connecting to a workspace

• IWorkspaceFactory.Open—The Open method takes as input a set of connection properties that specify the workspace to establish a connection with.
• IWorkspaceFactory.OpenFromFile—The OpenFromFile method takes the path name of a file or directory that represents a file-based workspace, a local geodatabase workspace, or an ArcSDE connection file and returns the appropriate workspace.
• IWorkspaceFactory2.OpenFromString—The OpenFromString method on the IWorkspaceFactory2 interface was added to allow the opening of a workspace using a connection string that describes the connection properties for the workspace. The connection string is a collection of name value pairs separated by semicolons (;).

Connecting to file geodatabases

[C#]

// For example, path = @"C:\myData\myfGDB.gdb".

public static IWorkspace FileGdbWorkspaceFromPath(String path){ 

   Type factoryType = Type.GetTypeFromProgID(

        "esriDataSourcesGDB.FileGDBWorkspaceFactory");

    IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance

        (factoryType);

    return workspaceFactory.OpenFromFile(path, 0);}

Connecting to personal geodatabases

[C#]

// For example, path = @"C:\myData\mypGDB.mdb".

public static IWorkspace AccessWorkspaceFromPath(String path){

    Type factoryType = Type.GetTypeFromProgID(

        "esriDataSourcesGDB.AccessWorkspaceFactory");

    IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance

        (factoryType);

    return workspaceFactory.OpenFromFile(path, 0);}

Connecting to enterprise ArcSDE geodatabases

• SERVER—The SDE server being connected to.
• INSTANCE—The instance being connected to.
• DATABASE—The database being connected to. The DATABASE property is optional and is required for ArcSDE instances that manage multiple databases (for example, SQL Server).
• USER—The connected user.
• PASSWORD—The connected user's password.
• AUTHENTICATION_MODE—The credential authentication mode of the connection. Acceptable values are the operating system authentication (OSA) and database management system (DBMS). The default is DBMS. If the AUTHENTICATION_MODE is OSA, the USER and PASSWORD properties are not required. OSA uses the operating system credentials to establish a connection with the database.
• VERSION—The transactional version to connect to. The acceptable value is a string that represents a transaction version name.
• HISTORICAL_NAME—The historical version to connect to. The acceptable value is a string that represents a historical marker name.
• HISTORICAL_TIMESTAMP—The moment in history to establish a historical version connection. The acceptable value is a date object containing a date time that represents a moment time stamp. The formatting of the date is DBMS specific (for example, SQLServer = "1/1/2006 12:00:01 AM").

Connecting to a transactional version

[C#]

// For example, server = "Kona".// Database = "SDE" or "" if Oracle.// Instance = "5151".// User = "vtest".// Password = "go".// Version = "SDE.DEFAULT".

public static IWorkspace ConnectToTransactionalVersion(String server, String  instance, String user, String password, String database, String version){

    IPropertySet propertySet = new PropertySetClass();

    propertySet.SetProperty("SERVER", server);

    propertySet.SetProperty("INSTANCE", instance);

    propertySet.SetProperty("DATABASE", database);

    propertySet.SetProperty("USER", user);

    propertySet.SetProperty("PASSWORD", password);

    propertySet.SetProperty("VERSION", version);

    Type factoryType = Type.GetTypeFromProgID(        "esriDataSourcesGDB.SdeWorkspaceFactory");

    IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance        (factoryType);

    return workspaceFactory.Open(propertySet, 0);}

Connecting to a historical marker name

[C#]

// For example, server = "Kona".// database = "sde" or "" if Oracle.// instance = "5151".// user = "vtest".// password = "go".// historicalName = "Year End 2006".

public static IWorkspace ConnectoToHistoricalVersion(String server, String instance,

    String user, String password, String database, String historicalName){

    IPropertySet propertySet = new PropertySetClass();

    propertySet.SetProperty("SERVER", server);

    propertySet.SetProperty("INSTANCE", instance);

    propertySet.SetProperty("DATABASE", database);

    propertySet.SetProperty("USER", user);

    propertySet.SetProperty("PASSWORD", password);

    propertySet.SetProperty("HISTORICAL_NAME", historicalName);

    Type factoryType = Type.GetTypeFromProgID( 

       "esriDataSourcesGDB.SdeWorkspaceFactory");

    IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance 

       (factoryType);

    return workspaceFactory.Open(propertySet, 0);}

Connecting to a historical time stamp

[C#]

// For example, server = "Kona".// database = "sde".// instance = "5151".// user = "vtest".// password = "go".// timestamp = "1/1/2006 12:00:01 AM".

public static IWorkspace ConnectToHistoricalTimestamp(String server, String instance,

    String user, String password, String database, String timestamp){

    IPropertySet propertySet = new PropertySetClass();

    propertySet.SetProperty("SERVER", server);

    propertySet.SetProperty("INSTANCE", instance);

    propertySet.SetProperty("DATABASE", database); 

   propertySet.SetProperty("USER", user); 

   propertySet.SetProperty("PASSWORD", password);   // Convert a string representing a date to a date object when using it   // throughout the archiving API.

    DateTime dateTime = Convert.ToDateTime(timestamp); 

   propertySet.SetProperty("HISTORICAL_TIMESTAMP", dateTime);

    Type factoryType = Type.GetTypeFromProgID(

        "esriDataSourcesGDB.SdeWorkspaceFactory"); 

   IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance  

      (factoryType); 

   return workspaceFactory.Open(propertySet, 0);}

[C#]

// For example, connectionFile = @"C:\myData\Connection to Kona.sde".

public static IWorkspace ArcSdeWorkspaceFromFile(String connectionFile){ 

   Type factoryType = Type.GetTypeFromProgID(

        "esriDataSourcesGDB.SdeWorkspaceFactory");

    IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance 

       (factoryType);

    return workspaceFactory.OpenFromFile(connectionFile, 0);}

[C#]

// For example, connectionString = "SERVER=Kona;DATABASE=sde;INSTANCE=5151;USER=Editor;PASSWORD=Editor;VERSION=sde.DEFAULT".

public static IWorkspace ArcSdeWorkspaceFromString(String connectionString){

    Type factoryType = Type.GetTypeFromProgID(

        "esriDataSourcesGDB.SdeWorkspaceFactory");

    IWorkspaceFactory2 workspaceFactory2 = (IWorkspaceFactory2)

        Activator.CreateInstance(factoryType);

    return workspaceFactory2.OpenFromString(connectionString, 0);}

Using the workspace factory

[C#]

// For example, for direct connect with OSA authentication.// Server = "tivo_sqlexpress".// Instance = "sde:sqlserver:tivo\\sqlexpress".// Database = "sewer".// Authentication_mode = "OSA".// Version = "dbo.DEFAULT".

public static IWorkspace WorkgroupArcSdeWorkspaceFromPropertySet(String server,

    String instance, String authenticationMode, String database, String version){

    IPropertySet propertySet = new PropertySetClass();

    propertySet.SetProperty("SERVER", server);

    propertySet.SetProperty("INSTANCE", instance);

    propertySet.SetProperty("DATABASE", database);

    propertySet.SetProperty("AUTHENTICATION_MODE", authenticationMode);

    propertySet.SetProperty("VERSION", version);

    Type factoryType = Type.GetTypeFromProgID(

        "esriDataSourcesGDB.SdeWorkspaceFactory");

    IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance 

       (factoryType);

    return workspaceFactory.Open(propertySet, 0);}

[C#]

// For example, connectionFile = @"C:\myData\Connection to tivo.sde".

public static IWorkspace WorkgroupArcSdeWorkspaceFromFile(String connectionFile){

    Type factoryType = Type.GetTypeFromProgID(

        "esriDataSourcesGDB.SdeWorkspaceFactory");

    IWorkspaceFactory workspaceFactory = (IWorkspaceFactory)Activator.CreateInstance

        (factoryType);

    return workspaceFactory.OpenFromFile(connectionFile, 0);}

[C#]

// For example, connectionString = "SERVER=tivo_sqlexpress;DATABASE=sewer;INSTANCE=sde:sqlserver:tivo\\sqlexpress;AUTHENTICATION_MODE=OSA;VERSION=dbo.DEFAULT".

public IWorkspace WorkgroupArcSdeWorkspaceFromString(String connectionString){

    Type factoryType = Type.GetTypeFromProgID(

        "esriDataSourcesGDB.SdeWorkspaceFactory");

    IWorkspaceFactory2 workspaceFactory2 = (IWorkspaceFactory2)

        Activator.CreateInstance(factoryType);

    return workspaceFactory2.OpenFromString(connectionString, 0);}

Using the DataServerManager

• VERSION—Transactional version to connect to. The acceptable value is a string that represents a transaction version name.
• HISTORICAL_NAME—Historical version to connect to. The acceptable value is a string that represents a historical marker name.
• HISTORICAL_TIMESTAMP—Moment in history to establish a historical version connection. The acceptable value is a date object containing a date time that represents a moment time stamp.

[C#]

// For example, serverName = "tivo\\sqlexpress".// gdbName = "sewer".// versionPropName = "VERSION".// versionName = "dbo.DEFAULT".

public static IWorkspace WorkgroupArcSdeWorkspaceFromDSM(String serverName, String    gdbName, String versionPropName, String versionName){ 

   // Create a Data Server Manager object.

    IDataServerManager dataServerManager = new DataServerManagerClass(); 

   // Set the server name and connect to the server.

    dataServerManager.ServerName = serverName;

    dataServerManager.Connect();    // Open one of the geodatabases in the database server.

    IDataServerManagerAdmin dataServerManagerAdmin = (IDataServerManagerAdmin)

        dataServerManager;

    IWorkspaceName workspaceName = dataServerManagerAdmin.CreateWorkspaceName 

       (gdbName, versionPropName, versionName);    // Cast from the workspace name to utilize the Open method. 

   IName name = (IName)workspaceName;

    IWorkspace workspace = (IWorkspace)name.Open();

    return workspace;}

---