Creating tables (ArcObjects .NET 10.5 SDK)

Summary

This topic shows how to create tables and object classes in a geodatabase.

In this topic

Creating a geodatabase table
Tables vs. object classes
Using IFieldChecker for field validation
CreateTable parameters
Additional code examples

Creating a geodatabase table

The CreateTable method can be used to create a table or object class in the geodatabase. Tables and object classes only exist at the workspace level and are not contained in feature datasets. See the following code examples:

[C#]

public IObjectClass CreateObjectClass(IWorkspace workspace, String className,
    IFields fields)
{
    IFeatureWorkspace featureWorkspace=(IFeatureWorkspace)workspace;
    IObjectClassDescription ocDescription=new ObjectClassDescriptionClass();

    // Use IFieldChecker to create a validated fields collection.
    IFieldChecker fieldChecker=new FieldCheckerClass();
    IEnumFieldError enumFieldError=null;
    IFields validatedFields=null;
    fieldChecker.ValidateWorkspace=workspace;
    fieldChecker.Validate(fields, out enumFieldError, out validatedFields);

    // The enumFieldError enumerator can be inspected at this point to determine 
    // which fields were modified during validation.
    ITable table=featureWorkspace.CreateTable(className, validatedFields,
        ocDescription.InstanceCLSID, null, "");
    return (IObjectClass)table;
}

[VB.NET]

Public Function CreateObjectClass(ByVal workspace As IWorkspace, ByVal className As String, ByVal fields As IFields) As IObjectClass
    Dim featureWorkspace As IFeatureWorkspace=CType(workspace, IFeatureWorkspace)
    Dim ocDescription As IObjectClassDescription=New ObjectClassDescriptionClass()
    
    ' Use IFieldChecker to create a validated fields collection.
    Dim fieldChecker As IFieldChecker=New FieldCheckerClass()
    Dim enumFieldError As IEnumFieldError=Nothing
    Dim validatedFields As IFields=Nothing
    fieldChecker.ValidateWorkspace=workspace
    fieldChecker.Validate(fields, enumFieldError, validatedFields)
    
    ' The enumFieldError enumerator can be inspected at this point to determine
    ' which fields were modified during validation.
    Dim table As ITable=featureWorkspace.CreateTable(className, validatedFields, ocDescription.InstanceCLSID, Nothing, "")
    Return CType(Table, IObjectClass)
End Function

Using the IObjectClassDescription interface of the ObjectClassDescription class is not required when creating an object class, but it can save time. The previous code example shows the InstanceCLSID property being used during the CreateTable call. The RequiredFields property can also be used to save time. For more information on using IObjectClassDescription when creating an object class, see CreateTable parameters in this topic.

For more information on how to connect to a workspace, see Connecting to geodatabases and databases. For more information on how to create a geodatabase, see Creating geodatabases.

Tables vs. object classes

The terms "table" and "object class" are often used interchangeably in the context of the geodatabase, but there are differences between the two. An object class is a special type of table, specifically one that has been registered with the geodatabase (meaning that the geodatabase system tables have references to it). Tables that are not object classes do not exhibit any geodatabase behavior, for example, they cannot have aliases, subtypes or domains assigned to their fields.

When creating a table in ArcCatalog, an object class is created by default, but the class identifier (CLSID) parameter of CreateTable can be used to create a table that is not registered with the geodatabase. Rather than passing in a valid unique identifier (UID) instance (this is discussed in more detail in the parameters section later in this topic), a null value indicates that an unregistered table should be created.

When discussing geodatabases, "table" generally means "object class."

Using IFieldChecker for field validation

Attempting to create an object class with invalid field names results in an error being raised when the IFeatureWorkspace.CreateTable method is called. The IFieldChecker interface provides data source-specific validation for fields collections. The IFieldChecker.Validate method takes a collection of fields as an input parameter and returns a field error enumerator, and a validated fields collection as output parameters. Before calling Validate, the ValidateWorkspace property must first be set to the workspace where the fields will be created.

The following are the four types of field name errors:

The field shares its name with a word reserved by the data source (for example, Table).
The field shares its name with a previously defined field.
The field contains an invalid character.
The field name exceeds the data source's maximum length for field names.

The code examples in this topic show how to use the IFieldChecker interface when creating a object class. For more information, see the IFieldChecker, IEnumFieldError and IFieldError interfaces.

CreateTable parameters

The following subsections describe setting the properties of a new table with the parameters of the CreateTable method. For more information about the properties of a table, see Defining tables.

Name

An object class's name identifies it in the geodatabase. Make sure the name of the object class is unique before calling CreateTable. This can be done by using the IWorkspace2.NameExists property (for geodatabase data sources only).

To verify that a name is appropriate for a specific workspace (as different data sources have different restrictions on names), use the IFieldChecker.ValidateTableName. Note that this method does not check if a dataset of the same name already exists, only whether the name is a reserved word, if it contains an invalid character, or if it has an invalid starting character.

Fields

Each object class has a collection of fields, which are the components that provide structure for the class. Unregistered tables do not require any specific fields (although they must have at least one field), but object classes require an ObjectID field. The IFields, IField, and IFieldEdit interfaces can be used to create and populate the set of fields for a feature class, and the RequiredFields property of the IObjectClassDescription interface can be used to obtain a collection of predefined required fields.

For object classes, RequiredFields returns a field collection containing only the ObjectID field. For information about adding more fields to a new or existing object class, see Creating fields.

CLSID and EXTCLSID

The optional CLSID and extension class identifier (EXTCLSID) parameters allow the calling application to specify the globally unique identifiers (GUIDs) for the objects that implement the instance and the class extension behavior for an object class.

If using the IObjectClassDescription interface, the InstanceCLSID and ClassExtensionCLSID properties can be used to specify the appropriate CLSID of the object class's Component Object Model (COM) class and optionally, of the class extension that provides customized behavior for the object class.

Valid values for CLSID are esriGeoDatabase.Object or any nonspatial object that extends esriGeoDatabase.Object. The ObjectClassDescription class returns the GUID for esriGeodatabase.Object from its InstanceCLSID property. If no CLSID is passed in, the resulting table is not created as an object class and is not registered with the geodatabase (it will have an ObjectClassID of –1). Supplying the object class CLSID, allows the table to take advantage of geodatabase behavior, such as aliases, subtypes, and so on.

The EXTCLSID parameter is only required if an extension is being assigned to the object class. In most cases, this parameter can be provided with a null value. Using the ClassExtensionCLSID property of the ObjectClassDescription class is equivalent to passing in a null value. Class extensions allow the object class to perform tasks, such as custom validation and event handling. Note that unregistered tables (with an ObjectClassID of –1) cannot have class extensions. For more information on class extensions, see Creating class extensions.

Configuration keyword

The optional configurationKeyword parameter allows the application to control the physical layout for this table in the underlying relational database management system (RDBMS) or file geodatabase. For example, in the case of an Oracle database, the configuration keyword controls the table space where the table is created, the initial and next extents, and other properties.

The configurationKeywords for an ArcSDE instance are set up by the ArcSDE data administrator. The list of available keywords supported by a workspace can be obtained using the IWorkspaceConfiguration interface.

The configuration keywords for a file geodatabase are predefined. In most cases, the Defaults keyword should be used.

Additional code examples

The following code examples creates an object class by adding an additional field (a text field called Name) to the ObjectClassDescription-defined RequiredFields. It also uses the IWorkspace2.NameExists property and the IFieldChecker.ValidateTableName method to validate the name of the object class.

[C#]

public IObjectClass CreateObjectClassWithFields(IWorkspace workspace, String
    className)
{
    // Cast the workspace to IFeatureWorkspace and IWorkspace2. An explicit cast is not used
    // for IWorkspace2 because not all workspaces implement it.
    IFeatureWorkspace featureWorkspace=(IFeatureWorkspace)workspace;
    IWorkspace2 workspace2=workspace as IWorkspace2;

    // See if a class with the provided name already exists. If so, return it.
    // Note that this will not work with file-based workspaces, such as shapefile workspaces.
    if (workspace2 != null)
    {
        if (workspace2.get_NameExists(esriDatasetType.esriDTTable, className))
        {
            ITable existingTable=featureWorkspace.OpenTable(className);
            return (IObjectClass)existingTable;
        }
    }

    // Use IFieldChecker.ValidateTableName to validate the name of the class. The 
    // tableNameErrorType variable is not used in this example, but it indicates the reasons 
    // the table name was invalid, if any.
    IFieldChecker fieldChecker=new FieldCheckerClass();
    String validatedClassName=null;
    fieldChecker.ValidateWorkspace=workspace;
    int tableNameErrorType=fieldChecker.ValidateTableName(className, out
        validatedClassName);

    // Create an object class description and get the required fields from it.
    IObjectClassDescription ocDescription=new ObjectClassDescriptionClass();
    IFields fields=ocDescription.RequiredFields;
    IFieldsEdit fieldsEdit=(IFieldsEdit)fields;

    // Add the Name field to the required fields.
    IField nameField=new FieldClass();
    IFieldEdit nameFieldEdit=(IFieldEdit)nameField;
    nameFieldEdit.Name_2="Name";
    nameFieldEdit.Type_2=esriFieldType.esriFieldTypeString;
    fieldsEdit.AddField(nameField);

    // Use the field checker created earlier to validate the fields.
    IEnumFieldError enumFieldError=null;
    IFields validatedFields=null;
    fieldChecker.Validate(fields, out enumFieldError, out validatedFields);

    // Create and return the object class.
    ITable table=featureWorkspace.CreateTable(validatedClassName, validatedFields,
        ocDescription.InstanceCLSID, null, "");
    return (IObjectClass)table;
}

[VB.NET]

Public Function CreateObjectClassWithFields(ByVal workspace As IWorkspace, ByVal className As String) As IObjectClass
    ' Cast the workspace to IFeatureWorkspace and IWorkspace2. An explicit cast is not used
    ' for IWorkspace2 because not all workspaces implement it.
    Dim featureWorkspace As IFeatureWorkspace=CType(workspace, IFeatureWorkspace)
    Dim workspace2 As IWorkspace2=TryCast(workspace, IWorkspace2)
    
    ' See if a class with the provided name already exists. If so, return it.
    ' Note that this will not work with file-based workspaces, such as shapefile workspaces.
    If Not workspace2 Is Nothing Then
        If workspace2.NameExists(esriDatasetType.esriDTTable, className) Then
            Dim existingTable As ITable=featureWorkspace.OpenTable(className)
            Return CType(existingTable, IObjectClass)
        End If
    End If
    
    ' Use IFieldChecker.ValidateTableName to validate the name of the class. The
    ' tableNameErrorType variable is not used in this example, but it indicates the reasons
    ' the table name was invalid, if any.
    Dim fieldChecker As IFieldChecker=New FieldCheckerClass()
    Dim validatedClassName As String=Nothing
    fieldChecker.ValidateWorkspace=workspace
    Dim tableNameErrorType As Integer=fieldChecker.ValidateTableName(className, validatedClassName)
    
    ' Create an object class description and get the required fields from it.
    Dim ocDescription As IObjectClassDescription=New ObjectClassDescriptionClass()
    Dim fields As IFields=ocDescription.RequiredFields
    Dim fieldsEdit As IFieldsEdit=CType(fields, IFieldsEdit)
    
    ' Add the Name field to the required fields.
    Dim nameField As IField=New FieldClass()
    Dim nameFieldEdit As IFieldEdit=CType(nameField, IFieldEdit)
    nameFieldEdit.Name_2="Name"
    nameFieldEdit.Type_2=esriFieldType.esriFieldTypeString
    fieldsEdit.AddField(nameField)
    
    ' Use the field checker created earlier to validate the fields.
    Dim enumFieldError As IEnumFieldError=Nothing
    Dim validatedFields As IFields=Nothing
    fieldChecker.Validate(fields, enumFieldError, validatedFields)
    
    ' Create and return the object class.
    Dim table As ITable=featureWorkspace.CreateTable(validatedClassName, validatedFields, ocDescription.InstanceCLSID, Nothing, "")
    Return CType(table, IObjectClass)
End Function

The following code example shows how to create an object class with an ObjectID field and a text field without using a class description.

[C#]

public IObjectClass CreateWithoutClassDescription(IWorkspace workspace, String
    className)
{
    // Cast the workspace to the IFeatureWorkspace interface.
    IFeatureWorkspace featureWorkspace=(IFeatureWorkspace)workspace;

    // Create the fields collection.
    IFields fields=new FieldsClass();
    IFieldsEdit fieldsEdit=(IFieldsEdit)fields;

    // Add the ObjectID field.
    IField oidField=new FieldClass();
    IFieldEdit oidFieldEdit=(IFieldEdit)oidField;
    oidFieldEdit.Name_2="OID";
    oidFieldEdit.Type_2=esriFieldType.esriFieldTypeOID;
    fieldsEdit.AddField(oidField);

    // Add the text field.
    IField nameField=new FieldClass();
    IFieldEdit nameFieldEdit=(IFieldEdit)nameField;
    nameFieldEdit.Name_2="Name";
    nameFieldEdit.Type_2=esriFieldType.esriFieldTypeString;
    fieldsEdit.AddField(nameField);

    // Use IFieldChecker to create a validated fields collection.
    IFieldChecker fieldChecker=new FieldCheckerClass();
    IEnumFieldError enumFieldError=null;
    IFields validatedFields=null;
    fieldChecker.ValidateWorkspace=workspace;
    fieldChecker.Validate(fields, out enumFieldError, out validatedFields);

    // The enumFieldError enumerator can be inspected at this point to determine 
    // which fields were modified during validation.

    // Create a UID for the CLSID parameter of CreateTable. For a regular object class,
    // you should use esriGeodatabase.Object.
    UIDClass instanceUID=new UIDClass();
    instanceUID.Value="esriGeodatabase.Object";

    // Create and return the object class.
    ITable table=featureWorkspace.CreateTable(className, validatedFields,
        instanceUID, null, "");
    return (IObjectClass)table;
}

[VB.NET]

Public Function CreateWithoutClassDescription(ByVal workspace As IWorkspace, ByVal className As String) As IObjectClass
    ' Cast the workspace to the IFeatureWorkspace interface.
    Dim featureWorkspace As IFeatureWorkspace=CType(workspace, IFeatureWorkspace)
    
    ' Create the fields collection.
    Dim fields As IFields=New FieldsClass()
    Dim fieldsEdit As IFieldsEdit=CType(fields, IFieldsEdit)
    
    ' Add the ObjectID field.
    Dim oidField As IField=New FieldClass()
    Dim oidFieldEdit As IFieldEdit=CType(oidField, IFieldEdit)
    oidFieldEdit.Name_2="OID"
    oidFieldEdit.Type_2=esriFieldType.esriFieldTypeOID
    fieldsEdit.AddField(oidField)
    
    ' Add the text field.
    Dim nameField As IField=New FieldClass()
    Dim nameFieldEdit As IFieldEdit=CType(nameField, IFieldEdit)
    nameFieldEdit.Name_2="Name"
    nameFieldEdit.Type_2=esriFieldType.esriFieldTypeString
    fieldsEdit.AddField(nameField)
    
    ' Use IFieldChecker to create a validated fields collection.
    Dim fieldChecker As IFieldChecker=New FieldCheckerClass()
    Dim enumFieldError As IEnumFieldError=Nothing
    Dim validatedFields As IFields=Nothing
    fieldChecker.ValidateWorkspace=workspace
    fieldChecker.Validate(fields, enumFieldError, validatedFields)
    
    ' The enumFieldError enumerator can be inspected at this point to determine
    ' which fields were modified during validation.
    
    ' Create a UID for the CLSID parameter of CreateTable. For a regular object class,
    ' you should use esriGeodatabase.Object.
    Dim instanceUID As UID=New UID()
    instanceUID.Value="esriGeodatabase.Object"
    
    ' Create and return the object class.
    Dim table As ITable=featureWorkspace.CreateTable(className, validatedFields, instanceUID, Nothing, "")
    Return CType(table, IObjectClass)
End Function

Development licensing	Deployment licensing
ArcGIS Desktop Basic	ArcGIS Desktop Basic
ArcGIS Desktop Standard	ArcGIS Desktop Standard
ArcGIS Desktop Advanced	ArcGIS Desktop Advanced
Engine Developer Kit	Engine: Geodatabase Update

Creating tables

In this topic

See Also: