In this topic
- About data conversion and transfer
- Name objects and conversion methods
- IFeatureDataConverter and IFeatureDataConverter2
- IGeoDBDataTransfer
- IExportOperation
- IDataset.Copy
- IWorkspaceFactory.Copy and IWorkspaceFactory.Move
About data conversion and transfer
Within the geodatabase and geodatabase user interface (UI) libraries, the following five main interfaces are involved with transferring datasets from one workspace to another:
- IFeatureDataConverter and IFeatureDataConverter2
- IGeoDBDataTransfer (also known as copy/paste)
- IDataset (specifically, the Copy method)
- IWorkspaceFactory (specifically, the Copy and Move methods)
- IExportOperation
In addition to these classes and interfaces, other options for transferring data exist. The following table shows an overview of the benefits and drawbacks of each:
Method |
What is transferred |
Works with query filter |
Crosses data sources |
Works with edit session |
ArcGIS Desktop/ ArcGIS Engine |
IFeatureDataConverter[2] |
Single table, feature class, or feature dataset |
True |
True |
False |
Both |
IGeoDBDataTransfer |
Multiple tables, feature classes, and/or feature datasets, and domains from geodatabases |
False |
False |
False |
Both |
IExportOperation (GeodatabaseUI) |
Single table or feature class |
True |
True |
False |
ArcGIS for Desktop |
IDataset.Copy |
Single dataset from a
file-based data source |
False |
False |
False |
Both |
IWorkspaceFactory
(Copy and Move methods) |
Local (personal or file) geodatabase, or an SDE connection file |
False |
False |
False |
Both |
IGdbXmlExport and IGdbXmlImport (GeoDatabaseDistributed) |
Entire workspace (schema, data optional), one or more datasets (schema, data optional), or a record set * |
False |
False |
False |
Both |
IObjectLoader (EditorExt) |
Individual rows from one dataset to another existing dataset |
True |
True |
True |
ArcGIS for Desktop |
* The IGdbXmlExport and IGdbXmlImport interfaces indirectly transfer data between geodatabases by first converting the dataset schema (and optionally, the data) to Extensible Markup Language (XML), then from XML back to its original form. |
To summarize the previous table, the following situations are appropriate for each method:
- IFeatureDataConverter - Use when copying a single dataset or feature dataset and fine-grained control is necessary. This includes applying a query filter to restrict the rows that are copied, modifying the geometry definition, and applying a configuration key. Also useful for transferring datasets from one data source to another.
- IGeoDBDataTransfer - Use when copying one or more geodatabase datasets within the same geodatabase or to another geodatabase.
- IExportOperation - Use when copying a single dataset to another workspace and a query filter or selection set is necessary. Also useful for transferring datasets from one data source to another.
- IDataset.Copy - Use when copying a dataset from a file-based data source (such as a shapefile, a DBase .DBF table, or a coverage feature class) to another workspace.
- IWorkspaceFactory (Copy and Move methods) - Use when copying or moving an entire local geodatabase or an SDE connection file.
- IGdbXmlExport and IGdbXmlImport - Use when XML data is required, or working in a disconnected environment.
- IObjectLoader - Use when copying individual rows to an existing dataset.
The last two methods in the preceding list are outside the scope of this topic. For more information, see the following:
- IGdbXmlExport and IGdbXmlImport:
- IObjectLoader:
- IObjectLoader (ArcGIS Desktop only)
Name objects and conversion methods
Many of the application programming interfaces (APIs) for data transfer involve the use of name objects. A name object is a lightweight representation of a dataset or a workspace that provides basic information, such as name and location, without requiring the client to open the dataset or the workspace. A name object can also represent a dataset that does not currently exist - they are used in this way with the IFeatureDataConverter and IExportOperation interfaces.
To get a name object for an existing dataset, there are the following three main options:
- Create a name object of the appropriate type (that is, FeatureClassName), cast it to the IDatasetName interface, and set the Name and WorkspaceName properties. This option requires having a name object for the dataset's workspace (and feature dataset, if applicable), but this can be created in a similar fashion.
- Generate a name object from an open dataset. After casting a dataset to the IDataset interface, the FullName property can be used to create a name object. This is only applicable for existing datasets, so it is not an option in cases where a name object represents a dataset to be created.
- Browse the dataset's container for its name object. An example of this is the IWorkspace.DatasetNames method, which returns an enumerator of name objects for a specific dataset type. Again, this is not an option for datasets that do not exist.
IFeatureDataConverter and IFeatureDataConverter2
The feature data converter copies a dataset within a workspace or to another workspace (of the same data source type or another data source type). The IFeatureDataConverter interface allows fine-grained control over the process of converting a dataset, including the following:
- Application of a query filter or a spatial filter to restrict the rows transferred to the new dataset.
- Application of a query filter's SubFields properties to restrict the fields transferred to the new dataset.
- Modification of the fields used in the new dataset (to some extent). Examples of this include changing a field's name and length, and in some cases, its type (that is, a double field can be converted to an integer field).
- Providing a new GeometryDef object to replace the existing geometry definition.
- Setting a configuration keyword for the dataset.
Not all of these are applicable to every type of conversion, for example, a table cannot be given a GeometryDef and a query filter cannot be used when converting a feature dataset.
In addition to the capabilities previously listed, the IFeatureDataConverter2 interface includes the option of providing a selection set to its ConvertFeatureClass and ConvertTable methods. This is particularly useful when creating a new dataset from the selected features of a feature layer.
The ConvertFeatureClass and ConvertTable methods of both feature data converter interfaces have an IEnumInvalidObject return type. This enumerator returns the Object IDs for each row or feature that could not be successfully converted, with a short description explaining why the conversion was unsuccessful. An example of why a conversion can fail is when the new dataset contains a string field with a shorter length than its corresponding field in the original dataset, and an object's value for that field exceeds the new length; however, it is important to remember the rejection of an individual row or feature does not cancel the entire operation.
The ConvertFeatureDataset method converts a feature dataset from one data source to another; however, relatively few data sources support feature datasets (compared to feature classes and tables), so it is not used as often as the other two conversion methods, and in most cases, IGeoDBDataTransfer is a better option for copying a feature dataset. This is especially true because ConvertFeatureDataset only transfers children that are feature classes, whereas IGeoDBDataTransfer includes other types of datasets, such as relationship classes, topologies, and geometric networks. The options available during conversion are significantly less than the other two methods, but a geometry definition and a configuration key can still be applied. Since a feature dataset does not include rows or features, this method has a void return type. For more information, see Converting simple data.
IGeoDBDataTransfer
Using the IGeoDBDataTransfer interface is equivalent to using the Copy and Paste commands within ArcCatalog for geodatabase datasets. It allows one or more datasets to be copied within or across geodatabases. The options available with this interface are significantly less than those of the IFeatureDataConverter methods, but in many cases this simplifies the overhead preparation required for the transfer.
One major advantage of this interface over the feature data converter is that it can be used to transfer nearly any type of geodatabase object, including relationship classes, topologies, and geometric networks. It also transfers datasets and objects that are associated with a copied object automatically. For example, if this interface is used to transfer a feature class that utilizes domains or representation classes, the process detects these and automatically transfers them with the feature class.
The only customizable aspect of this process is through a generated name mapping enumerator. The Transfer method requires a name mapping enumerator (IEnumNameMapping) that can be generated using the GenerateNameMapping method. Although the main reason to modify the name mappings is to resolve name conflicts (this occurs if a dataset of the same name exists in the target workspace), the INameMapping interface exposes properties that can be used to set the names and configuration keywords of the new datasets. For more information, see Copying and pasting geodatabase datasets
IExportOperation
The IExportOperation interface is effectively a "wrapped" version of the feature data converter. It allows a feature class or a table to be copied within its existing workspace or to another workspace (of the same or another type). The following are the three main differences between using IExportOperation and IFeatureDataConverter:
- It is slightly less configurable. In some cases this might be a disadvantage, but in cases where modification of objects like the fields collection is not required, this reduces the overhead preparation involved.
- IExportOperation displays a progress bar during operation. This can be useful for graphical user interface (GUI) applications, but might be inappropriate for console applications or processes intended to be silent.
- IExportOperation is located in the GeodatabaseUI library, meaning it is only available to ArcGIS Desktop users.
IDataset.Copy
The IDataset.Copy method allows a dataset from a file-based data source (such as a shapefile, a database file format [DBF] table, or a coverage feature class) to be copied to another workspace of the same type. There are virtually no configurable options in this process, as the method only takes two parameters - the name and workspace of the new dataset.
IWorkspaceFactory.Copy and IWorkspaceFactory.Move
IWorkspaceFactory.Copy and IWorkspaceFactory.Move allow a local geodatabase (a personal or file geodatabase) or an SDE connection file to be copied or moved within the file system. Both methods require workspace name objects. See the following:
- Copy requires a name object for the existing workspace and for the workspace to be created.
- Move only requires a name object for the existing workspace.
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 |