About data conversion and transfer

In this topic

---

Overview

Within the geodatabase library, there are five main interfaces involved with transferring datasets from one workspace to another: IFeatureDataConverter (and IFeatureDataConverter2 ), IGeoDBDataTransfer (also known as copy/paste), IDataset(specifically, the copy method) and IWorkspaceFactory(specifically, the  copy and move methods).

In addition to these classes and interfaces, several other options for transferring data exist. The following table gives an overview of the benefits and drawbacks of each:

Method	What is transferred	Works with a query filter	Crosses data sources	Works with edit session	Desktop / Engine
IFeatureDataConverter[2]	A single table, feature class, or feature dataset	True	True	False	Both
IGeoDBDataTransfer	Multiple tables, feature classes, and/or feature datasets (as well as their domains) from geodatabases	False	False	False	Both
IDataset.copy()	A single dataset from a file-based data source	False	False	False	Both
IWorkspaceFactory (Copy and Move methods)	A local (Personal or File) geodatabase, or an SDE connection file	False	False	False	Both
IGdbXmlExport and IGdbXmlImport (GeoDatabaseDistributed)	An entire workspace (schema, data optional), one or more datasets (schema, data optional), or a record set *	False	False	False	Both
IObjectLoader (EditorExt) Desktop only	Individual rows from one dataset to another existing dataset	True	True	True	Desktop

 * The IGdbXmlExport and IGdbXmlImport interfaces indirectly transfer data between geodatabases by first converting the dataset schema (and, optionally, the data) to XML and then from XML back to its original form.

To summarize the table above, the following situations are appropriate for each method:

The final two methods are outside the scope of this document. For more information on them, see the following articles:

Name objects and conversion methods

Many of the 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 some basic information, such as name and location, without requiring the client to actually open the dataset or the workspace. A name object can also represent a dataset that doesn't 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 three main options:

IFeatureDataConverter and IFeatureDataConverter2

The feature data converter will copy 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:

In addition to the capabilities listed above, 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, along with a short description explaining why the conversion was unsuccessful. An example of why a conversion may 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. It is important to keep in mind that the rejection of an individual row or feature does not cancel the entire operation, however.

The convertFeatureDataset() method will convert 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 isn't 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() will only transfer children that are feature classes, whereas IGeoDBDataTransfer will include 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 doesn't actually include rows or features itself, this method has a void return type.

For more information, see the following article:

IGeoDBDataTransfer

Using the GeoDBDataTransfer class is equivalent to using the Copy and Paste commands within ArcMap 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, 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 will detect these and automatically transfer them along 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 already exists in the target workspace), the INameMapping interface exposes properties which can be used to set the names and configuration keywords of the new datasets.

For more information, see the following article:

IDataset.copy

The IDataset.copy() method allows a dataset from a file-based data source (such as a shapefile, a 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: Copy requires a name object for the existing workspace and for the workspace to be created, while move() only requires a name object for the existing workspace.