This documentation is archived and is not being maintained.

MergeSynchronizationAgent Class

Provides the functionality of the Replication Merge Agent.

Namespace: Microsoft.SqlServer.Replication
Assembly: Microsoft.SqlServer.Replication (in microsoft.sqlserver.replication.dll)

[GuidAttribute("ee5ee47e-6d29-448f-b2d2-f8e632db336a")] 
[ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)] 
[ComVisibleAttribute(true)] 
[ComSourceInterfacesAttribute(typeof(IComStatusEvent))] 
[PermissionSetAttribute(SecurityAction.Demand, Name="FullTrust")] 
public class MergeSynchronizationAgent : MarshalByRefObject, IDisposable, IMergeSynchronizationAgent
/** @attribute GuidAttribute("ee5ee47e-6d29-448f-b2d2-f8e632db336a") */ 
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) */ 
/** @attribute ComVisibleAttribute(true) */ 
/** @attribute ComSourceInterfacesAttribute(Microsoft.SqlServer.Replication.IComStatusEvent) */ 
/** @attribute PermissionSetAttribute(SecurityAction.Demand, Name="FullTrust") */ 
public class MergeSynchronizationAgent extends MarshalByRefObject implements IDisposable, IMergeSynchronizationAgent
GuidAttribute("ee5ee47e-6d29-448f-b2d2-f8e632db336a") 
ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) 
ComVisibleAttribute(true) 
ComSourceInterfacesAttribute(Microsoft.SqlServer.Replication.IComStatusEvent) 
public class MergeSynchronizationAgent extends MarshalByRefObject implements IDisposable, IMergeSynchronizationAgent

The MergeSynchronizationAgent class supports the ability to do the following replication tasks:

  • Synchronize subscriptions.

  • Specify whether only the upload phase, only the download phase, or both phases are run during synchronization.

  • Validate that a subscription has the expected data.

  • Specify a different snapshot folder, from which the initial snapshot for a subscription can be applied.

The MergeSynchronizationAgent class can be used with Publishers and Subscribers that are running on both SQL Server 2000 and SQL Server 2005.

A MergeSynchronizationAgent class cannot be used with Distributors that are running on SQL Server 2000.


System.Object
   System.MarshalByRefObject
    Microsoft.SqlServer.Replication.MergeSynchronizationAgent

In the following example, the Synchronize method is called on the instance of the MergeSynchronizationAgent class that is accessed from the SynchronizationAgent property to synchronize the push subscription.

// Define the server, publication, and database names.
string subscriberName = subscriberInstance;
string publisherName = publisherInstance;
string publicationName = "AdvWorksSalesOrdersMerge";
string subscriptionDbName = "AdventureWorksReplica";
string publicationDbName = "AdventureWorks";

// Create a connection to the Publisher.
ServerConnection conn = new ServerConnection(publisherName);

MergeSubscription subscription;

try
{
    // Connect to the Publisher
    conn.Connect();

    // Define the subscription.
    subscription = new MergeSubscription();
    subscription.ConnectionContext = conn;
    subscription.DatabaseName = publicationDbName;
    subscription.PublicationName = publicationName;
    subscription.SubscriptionDBName = subscriptionDbName;
    subscription.SubscriberName = subscriberName;

    // If the push subscription exists, start the synchronization.
    if (subscription.LoadProperties())
    {
        // Check that we have enough metadata to start the agent.
        if (subscription.SubscriberSecurity != null)
        {
            // Synchronously start the Merge Agent for the subscription.
            subscription.SynchronizationAgent.Synchronize();
        }
        else
        {
            throw new ApplicationException("There is insufficent metadata to " +
                "synchronize the subscription. Recreate the subscription with " +
                "the agent job or supply the required agent properties at run time.");
        }
    }
    else
    {
        // Do something here if the push subscription does not exist.
        throw new ApplicationException(String.Format(
            "The subscription to '{0}' does not exist on {1}",
            publicationName, subscriberName));
    }
}
catch (Exception ex)
{
    // Implement appropriate error handling here.
    throw new ApplicationException("The subscription could not be synchronized.", ex);
}
finally
{
    conn.Disconnect();
}

In the following example, an instance of the MergeSynchronizationAgent class is used to synchronize a merge subscription. Because the pull subscription was created by using a value of false for CreateSyncAgentByDefault, additional properties must be supplied.

// Define the server, publication, and database names.
string subscriberName = subscriberInstance;
string publisherName = publisherInstance;
string distributorName = distributorInstance;
string publicationName = "AdvWorksSalesOrdersMerge";
string subscriptionDbName = "AdventureWorksReplica";
string publicationDbName = "AdventureWorks";
string hostname = @"adventure-works\garrett1";
string webSyncUrl = "https://" + publisherInstance + "/SalesOrders/replisapi.dll";

// Create a connection to the Subscriber.
ServerConnection conn = new ServerConnection(subscriberName);

MergePullSubscription subscription;
MergeSynchronizationAgent agent;

try
{
    // Connect to the Subscriber.
    conn.Connect();

    // Define the pull subscription.
    subscription = new MergePullSubscription();
    subscription.ConnectionContext = conn;
    subscription.DatabaseName = subscriptionDbName;
    subscription.PublisherName = publisherName;
    subscription.PublicationDBName = publicationDbName;
    subscription.PublicationName = publicationName;

    // If the pull subscription exists, then start the synchronization.
    if (subscription.LoadProperties())
    {
        // Get the agent for the subscription.
        agent = subscription.SynchronizationAgent;

        // Check that we have enough metadata to start the agent.
        if (agent.PublisherSecurityMode == null)
        {
            // Set the required properties that could not be returned
            // from the MSsubscription_properties table. 
            agent.PublisherSecurityMode = SecurityMode.Integrated;
            agent.DistributorSecurityMode = SecurityMode.Integrated;
            agent.Distributor = publisherName;
            agent.HostName = hostname;

            // Set optional Web synchronization properties.
            agent.UseWebSynchronization = true;
            agent.InternetUrl = webSyncUrl;
            agent.InternetSecurityMode = SecurityMode.Standard;
            agent.InternetLogin = winLogin;
            agent.InternetPassword = winPassword;
        }
        // Enable agent output to the console.
        agent.OutputVerboseLevel = 1;
        agent.Output = "";

        // Synchronously start the Merge Agent for the subscription.
        agent.Synchronize();
    }
    else
    {
        // Do something here if the pull subscription does not exist.
        throw new ApplicationException(String.Format(
            "A subscription to '{0}' does not exist on {1}",
            publicationName, subscriberName));
    }
}
catch (Exception ex)
{
    // Implement appropriate error handling here.
    throw new ApplicationException("The subscription could not be " +
        "synchronized. Verify that the subscription has " +
        "been defined correctly.", ex);
}
finally
{
    conn.Disconnect();
}

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Development Platforms

For a list of the supported platforms, see Hardware and Software Requirements for Installing SQL Server 2005.

Target Platforms

Release

History

14 April 2006

Changed content:
  • Starting with Service Pack 1, applications that use the MergeSynchronizationAgent object no longer must use a single-threaded apartment threading model. The Thread Safety section was changed to reflect this new behavior.

Show: