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


This document was published with and applies to ArcGIS 9.3.
A 10 version also exists.
Summary Prior to creating a replica, it is recommended that a well-defined data model be in place. However, even with well-defined data models, schema changes within the geodatabase may be required from time to time. 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 may 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.

Development licensing Deployment licensing
ArcEditor ArcEditor
ArcInfo ArcInfo
Engine Developer Kit Engine Runtime: Geodatabase Update

To use the code in this topic, reference the following namespaces via the using (C#) or Imports (VB .NET) statements. It is also necessary to add the corresponding references to the project to gain access to these APIs.

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 both 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
To include existing rows when adding the table or feature class, use the following procedure:
  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 prior to 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:
 
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 don't 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 in a way appropriate to 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 in a way appropriate to 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 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'");

[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:

How to get a list of schema differences between replicas