How to add a feature class or table to an existing replica

Summary Before creating a replica, make sure a well-defined data model is in place. However, even with well-defined data models, schema changes within the geodatabase can be required periodically. If schema changes are applied to data that has already been replicated, tools are provided to determine schema differences between replica pairs and to apply schema changes across replicas.

In addition to modifying schema already in a replica, it might be necessary to add a feature class or table to an existing replica. This topic describes how to use the application programming interface (API) to accomplish this task. Since each replica in a replica pair is independent, the process must be executed on each replica. If the process is run on only one replica, changes applied to the new feature class or table will not be applied to the relative replica when synchronized.

The API supports adding simple feature classes and tables to a replica. The feature class or table must also not be involved in a relationship class.

In this topic

About adding a feature class or table to a replica

To add a feature class or table to an existing replica, add it to the parent and child replicas. Before adding the feature class or table to the replica, it must meet the replication data requirements.

Adding a table or feature class including existing rows

Do the following steps to include existing rows when adding the table or feature class:
  1. Make sure the feature class or table meets the data requirements in one of the replica geodatabases.
  2. Run the code to register the feature class or table with the replica (see the following code example) in the geodatabase referenced in Step 1.
  3. Copy and paste, or use data extraction to copy the rows you want to include in the replica to the relative replica.
  4. Register the data as versioned on the relative replica.
  5. Run the code to register the feature class or table with the relative replica (see the following code example).
If data already exists in both replica geodatabases, skip Step 3; however, make sure global ID values are consistent across the replica geodatabases.

Adding a table or feature class without including existing rows

When adding an empty table or feature class, or if existing rows should not be included, another procedure you can use is as follows:
  1. Make sure the feature class or table meets the data requirements in one of the replica geodatabases.
  2. Run the code to register the feature class or table with the replica (see the following code example) in the geodatabase referenced in Step 1.
  3. Use the tools for applying changes to create the feature class or table and register it with the replica in the relative replica geodatabase. The table or feature class should not exist in the relative replica geodatabase before executing this step.
Once the table or feature class has been added, edits on these datasets that meet the replica criteria will be applied during synchronization. Edits that were made before they were registered with the replica will not be synchronized.

Adding the feature class or table to the replica

To add the feature class or table to the replica, use the RegisterReplicaDataset method from the IWorkspaceReplicasAdmin2 interface. This method takes a replica dataset object that references the replica, as well as the feature class or table to add. It also takes parameters that describe the filters to apply when synchronizing changes.
The following method registers a simple feature class or table with an existing replica in the workspace. The parameters for this method are shown in the following table:
 
Parameter
Description
workspace
The workspace referencing the replica geodatabase.
replicaName
The name of the replica.
datasetName
The name of the feature class or table to add to the replica. This must be the fully qualified name if not connected as the owner of the table or feature class.
parentDatabase
The name of the database in which the table or feature class is stored in the parent replica geodatabase. For Oracle geodatabases, this can be a blank string.
parentOwner
The name of the database user that owns the table or feature class in the parent replica geodatabase.
datasetType
The dataset type. For this parameter, only esriDTFeatureClass or esriDTTable are acceptable.
rowsType
This defines the type of filter to apply to the newly added table or feature class. An esriRowsTypeAll filter applies any change to any row in the table or feature class on synchronize. If esriRowsTypeFilter is used, the geometry and queryDef settings determine what to synchronize. An esriRowsTypeNone filter prevents any changes from being synchronized. 
useGeometry
If useGeometry is true, the spatial criteria defined at replica creation will be applied when synchronizing changes to the newly added feature class. If false, the spatial criteria is ignored.
queryDef
This is a query that defines the rows to synchronize. Only rows satisfying this query will be synchronized. Use a blank string when you do not want to apply a definition query.
 
See the following code example:
 
[C#] 
// This method adds a feature class or table to a replica.
public void AddDatasetToReplica(IWorkspace workspace, String replicaName, String
    datasetName, String parentDatabase, String parentOwner, esriDatasetType
    datasetType, esriRowsType rowsType, Boolean useGeometry, String queryDef)
{
    // Find the replica.
    IWorkspaceReplicas2 workspaceReplicas2 = (IWorkspaceReplicas2)workspace;
    IReplica replica = workspaceReplicas2.get_ReplicaByName(replicaName);

    // Create a replica dataset for the new feature class or table.
    IReplicaDataset replicaDataset = new ReplicaDatasetClass();
    IReplicaDatasetEdit replicaDatasetEdit = (IReplicaDatasetEdit)replicaDataset;
    replicaDatasetEdit.Type = datasetType;
    replicaDatasetEdit.Name = datasetName;
    replicaDatasetEdit.ParentDatabase = parentDatabase;
    replicaDatasetEdit.ParentOwner = parentOwner;
    replicaDatasetEdit.ReplicaID = replica.ReplicaID;

    // Add the dataset. Note that the pSelID parameter is not currently supported
    // and should always be Nothing.
    IWorkspaceReplicasAdmin2 workspaceReplicasAdmin2 = (IWorkspaceReplicasAdmin2)
        workspaceReplicas2;
    try
    {
        workspaceReplicasAdmin2.RegisterReplicaDataset(replicaDataset, rowsType,
            useGeometry, queryDef, null, replica);
    }
    catch (COMException comExc)
    {
        // Handle the exception appropriately for the application.
    }
}
[VB.NET] 
' This method adds a feature class or table to a replica.

Public Sub AddDatasetToReplica(ByVal workspace As IWorkspace, ByVal replicaName As String, _
                               ByVal datasetName As String, ByVal parentDatabase As String, ByVal parentOwner As String, _
                               ByVal datasetType As esriDatasetType, ByVal rowsType As esriRowsType, ByVal useGeometry As Boolean, _
                               ByVal queryDef As String)
    
    ' Find the replica.
    Dim workspaceReplicas2 As IWorkspaceReplicas2 = CType(workspace, IWorkspaceReplicas2)
    Dim replica As IReplica = workspaceReplicas2.ReplicaByName(replicaName)
    
    ' Create a replica dataset for the new feature class or table.
    Dim replicaDataset As IReplicaDataset = New ReplicaDatasetClass()
    Dim replicaDatasetEdit As IReplicaDatasetEdit = CType(replicaDataset, IReplicaDatasetEdit)
    replicaDatasetEdit.Type = datasetType
    replicaDatasetEdit.Name = datasetName
    replicaDatasetEdit.ParentDatabase = parentDatabase
    replicaDatasetEdit.ParentOwner = parentOwner
    replicaDatasetEdit.ReplicaID = replica.ReplicaID
    
    ' Add the dataset. Note that the pSelID parameter is not currently supported
    ' and should always be Nothing.
    Dim workspaceReplicasAdmin2 As IWorkspaceReplicasAdmin2 = CType(workspaceReplicas2, IWorkspaceReplicasAdmin2)
    Try
    workspaceReplicasAdmin2.RegisterReplicaDataset(replicaDataset, rowsType, useGeometry, _
                                                   queryDef, Nothing, replica)
    Catch comExc As COMException
    ' Handle the exception appropriately for the application.
    End Try
End Sub
The following code example shows some examples of calling the AddDatasetToReplica method:
[C#] 
// 1. Adding a feature class to a replica with a spatial filter. In this case, rowsType is set to
// esriRowsTypeFilter and useGeom is true. This means that only edits to features intersecting
// the replica geoemtry will be applied on synchronize.
AddDatasetToReplica(workspace, "testReplica", "k1.dbo.Parcels", "k1", "DBO",
    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeFilter, true, "");

// 2. Adding the matching feature class from Example 1 to the relative replica. To get
// consistent results, apply the same criteria to the relative replica.
AddDatasetToReplica(workspace, "testReplica", "k2.dbo.Parcels", "k1", "DBO",
    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeFilter, true, "");

// 3. Adding a feature class with a querydef and a spatial filter. Here, edits to features
// meeting the spatial criteria and the query definition will be synchronized.
AddDatasetToReplica(workspace, "testReplica", "k1.dbo.Buildings", "k1", "DBO",
    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeFilter, true, 
    "Building_Phase = 'Complete'");

// 4. Adding a feature class with all rows. In this case, any edit to any feature will be applied
// when syncrhonize is run.
AddDatasetToReplica(workspace, "testReplica", "k1.dbo.California_Counties", "k1", 
    "DBO", esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeAll, false, 
    "");

// 5. Adding a table with a querydef. In this case, only edits to rows in the table that satisfy
// the querydef will be syncrhonized.
AddDatasetToReplica(workspace, "testReplica", "k1.dbo.Owners", "k1", "DBO",
    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeFilter, false, 
    "State_Name = 'California'");
[VB.NET] 
' 1. Adding a feature class to a replica with a spatial filter. In this case, rowsType is set to
' esriRowsTypeFilter and useGeom is true. This means that only edits to features intersecting
' the replica geoemtry will be applied on synchronize.
AddDatasetToReplica(workspace, "testReplica", "k1.dbo.Parcels", "k1", "DBO", _
                    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeFilter, True, "")

' 2. Adding the matching feature class from Example 1 to the relative replica. To get
' consistent results, apply the same criteria to the relative replica.
AddDatasetToReplica(workspace, "testReplica", "k2.dbo.Parcels", "k1", "DBO", _
                    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeFilter, True, "")

' 3. Adding a feature class with a querydef and a spatial filter. Here, edits to features
' meeting both the spatial criteria and the query definition will be synchronized.
AddDatasetToReplica(workspace, "testReplica", "k1.dbo.Buildings", "k1", "DBO", _
                    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeFilter, True, _
                    "Building_Phase = 'Complete'")

' 4. Adding a feature class with all rows. In this case, any edit to any feature will be applied
' when syncrhonize is run.
AddDatasetToReplica(workspace, "testReplica", "k1.dbo.California_Counties", "k1", "DBO", _
                    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeAll, False, "")

' 5. Adding a table with a querydef. In this case, only edits to rows in the table that satisfy
' the querydef will be syncrhonized.
AddDatasetToReplica(workspace, "testReplica", "k1.dbo.Owners", "k1", "DBO", _
                    esriDatasetType.esriDTFeatureClass, esriRowsType.esriRowsTypeFilter, False, _
                    "State_Name = 'California'")


See Also:

Getting a list of schema differences between replicas



To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcEditor ArcEditor
ArcInfo ArcInfo
Engine Developer Kit Engine Runtime: Geodatabase Update