Export (0) Print
Expand All
5 out of 7 rated this helpful - Rate this topic

How to: Create a Pull Subscription (RMO Programming)

Pull subscriptions can be created programmatically by using Replication Management Objects (RMO). The RMO classes used to create a pull subscription depend on the type of publication to which the subscription belongs.

  1. Create connections to both the Subscriber and Publisher by using the ServerConnection Class.

  2. Create an instance of the TransPublication class by using the Publisher connection from step 1. Specify Name, DatabaseName and ConnectionContext.

  3. Call the LoadProperties method. If this method returns false, either the properties specified in step 2 are incorrect or the publication does not exist on the server.

  4. Perform a bitwise logical AND (& in Visual C# and And in Visual Basic) between the Attributes property and AllowPull. If the result is None, set Attributes to the result of a bitwise logical OR (| in Visual C# and Or in Visual Basic) between Attributes and AllowPull. Then, call CommitPropertyChanges to enable pull subscriptions.

  5. If the subscription database does not exist, create it by using the Database class. For more information, see Creating, Altering, and Removing Databases.

  6. Create an instance of the TransPullSubscription class.

  7. Set the following subscription properties:

    • The ServerConnection to the Subscriber created in step 1 for ConnectionContext.
    • Name of the subscription database for DatabaseName.
    • Name of the Publisher for PublisherName.
    • Name of the publication database for PublicationDBName.
    • Name of the publication for PublicationName.
    • The Login and Password or SecurePassword fields of SynchronizationAgentProcessSecurity to provide the credentials for the Microsoft Windows account under which the Distribution Agent runs at the Subscriber. This account is used to make local connections to the Subscriber and to make remote connections using Windows Authentication.
      ms147314.note(en-US,SQL.90).gifNote:
      Setting SynchronizationAgentProcessSecurity is not required when the subscription is created by a member of the sysadmin fixed server role, however it is recommended. In this case, the agent will impersonate the SQL Server Agent account. For more information, see Replication Agent Security Model.

    • (Optional) A value of true for CreateSyncAgentByDefault to create an agent job that is used to synchronize the subscription. If you specify false (the default), the subscription can only be synchronized programmatically and you must specify additional properties of TransSynchronizationAgent when you access this object from the SynchronizationAgent property. For more information, see How to: Synchronize a Pull Subscription (RMO Programming).
      ms147314.note(en-US,SQL.90).gifNote:
      Microsoft SQL Server Express Edition does not support SQL Server Agent. When you specify a value of true for Express Edition Subscribers, the agent job is not created. However, important subscription-related metadata is stored at the Subscriber.

    • (Optional) Set the SqlStandardLogin and SqlStandardPassword or SecureSqlStandardPassword fields of DistributorSecurity when using SQL Server Authentication to connect to the Distributor.
  8. Call the Create method.

  9. Using the instance of the TransPublication class from step 2, call the MakePullSubscriptionWellKnown method to register the pull subscription with the Publisher. If this registration already exists, an exception occurs.

  1. Create connections to both the Subscriber and Publisher by using the ServerConnection class.

  2. Create an instance of the MergePublication class by using the Publisher connection from step 1. Specify Name, DatabaseName, and ConnectionContext.

  3. Call the LoadProperties method. If this method returns false, either the properties specified in step 2 are incorrect or the publication does not exist on the server.

  4. Perform a bitwise logical AND (& in Visual C# and And in Visual Basic) between the Attributes property and AllowPull. If the result is None, set Attributes to the result of a bitwise logical OR (| in Visual C# and Or in Visual Basic) between Attributes and AllowPull. Then, call CommitPropertyChanges to enable pull subscriptions.

  5. If the subscription database does not exist, create it by using the Database class. For more information, see Creating, Altering, and Removing Databases.

  6. Create an instance of the MergePullSubscription class.

  7. Set the following subscription properties:

    • The ServerConnection to the Subscriber created in step 1 for ConnectionContext.
    • Name of the subscription database for DatabaseName.
    • Name of the Publisher for PublisherName.
    • Name of the publication database for PublicationDBName.
    • Name of the publication for PublicationName.
    • The Login and Password or SecurePassword fields of SynchronizationAgentProcessSecurity to provide the credentials for the Microsoft Windows account under which the Merge Agent runs at the Subscriber. This account is used to make local connections to the Subscriber and to make remote connections using Windows Authentication.
      ms147314.note(en-US,SQL.90).gifNote:
      Setting SynchronizationAgentProcessSecurity is not required when the subscription is created by a member of the sysadmin fixed server role, however it is recommended. In this case, the agent will impersonate the SQL Server Agent account. For more information, see Replication Agent Security Model.

    • (Optional) A value of true for CreateSyncAgentByDefault to create an agent job that is used to synchronize the subscription. If you specify false (the default), the subscription can only be synchronized programmatically and you must specify additional properties of MergeSynchronizationAgent when you access this object from the SynchronizationAgent property. For more information, see How to: Synchronize a Pull Subscription (RMO Programming).
    • (Optional) Set the SqlStandardLogin and SqlStandardPassword or SecureSqlStandardPassword fields of DistributorSecurity when using SQL Server Authentication to connect to the Distributor.
    • (Optional) Set the SqlStandardLogin and SqlStandardPassword or SecureSqlStandardPassword fields of PublisherSecurity when using SQL Server Authentication to connect to the Publisher.
  8. Call the Create method.

  9. Using the instance of the MergePublication class from step 2, call the MakePullSubscriptionWellKnown method to register the pull subscription with the Publisher. If this registration already exists, an exception occurs.

This example creates a pull subscription to a transactional publication. The Microsoft Windows account credentials used to create the Distribution Agent job are passed at runtime.

// Define the Publisher, publication, and databases.
string publicationName = "AdvWorksProductTran";
string publisherName = publisherInstance;
string subscriberName = subscriberInstance;
string subscriptionDbName = "AdventureWorksReplica";
string publicationDbName = "AdventureWorks";

//Create connections to the Publisher and Subscriber.
ServerConnection subscriberConn = new ServerConnection(subscriberName);
ServerConnection publisherConn = new ServerConnection(publisherName);

// Create the objects that we need.
TransPublication publication;
TransPullSubscription subscription;

try
{
    // Connect to the Publisher and Subscriber.
    subscriberConn.Connect();
    publisherConn.Connect();

    // Ensure that the publication exists and that 
    // it supports pull subscriptions.
    publication = new TransPublication();
    publication.Name = publicationName;
    publication.DatabaseName = publicationDbName;
    publication.ConnectionContext = publisherConn;

    if (publication.IsExistingObject)
    {
        if ((publication.Attributes & PublicationAttributes.AllowPull) == 0)
        {
            publication.Attributes |= PublicationAttributes.AllowPull;
        }

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

        // Specify the Windows login credentials for the Distribution Agent job.
        subscription.SynchronizationAgentProcessSecurity.Login = winLogin;
        subscription.SynchronizationAgentProcessSecurity.Password = winPassword;

        // Make sure that the agent job for the subscription is created.
        subscription.CreateSyncAgentByDefault = true;

        // By default, subscriptions to transactional publications are synchronized 
        // continuously, but in this case we only want to synchronize on demand.
        subscription.AgentSchedule.FrequencyType = ScheduleFrequencyType.OnDemand;

        // Create the pull subscription at the Subscriber.
        subscription.Create();

        Boolean registered = false;

        // Verify that the subscription is not already registered.
        foreach (TransSubscription existing
            in publication.EnumSubscriptions())
        {
            if (existing.SubscriberName == subscriberName
                && existing.SubscriptionDBName == subscriptionDbName)
            {
                registered = true;
            }
        }
        if (!registered)
        {
            // Register the subscription with the Publisher.
            publication.MakePullSubscriptionWellKnown(
                subscriberName, subscriptionDbName,
                SubscriptionSyncType.Automatic,
                TransSubscriberType.ReadOnly);
        }
    }
    else
    {
        // Do something here if the publication does not exist.
        throw new ApplicationException(String.Format(
            "The publication '{0}' does not exist on {1}.",
            publicationName, publisherName));
    }
}
catch (Exception ex)
{
    // Implement the appropriate error handling here.
    throw new ApplicationException(String.Format(
        "The subscription to {0} could not be created.", publicationName), ex);
}
finally
{
    subscriberConn.Disconnect();
    publisherConn.Disconnect();
}

This example creates a pull subscription to a merge publication. The Windows account credentials used to create the Merge Agent job are passed at runtime.

// Define the Publisher, publication, and databases.
string publicationName = "AdvWorksSalesOrdersMerge";
string publisherName = publisherInstance;
string subscriberName = subscriberInstance;
string subscriptionDbName = "AdventureWorksReplica";
string publicationDbName = "AdventureWorks";
string hostname = @"adventure-works\garrett1";

//Create connections to the Publisher and Subscriber.
ServerConnection subscriberConn = new ServerConnection(subscriberName);
ServerConnection publisherConn = new ServerConnection(publisherName);

// Create the objects that we need.
MergePublication publication;
MergePullSubscription subscription;

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

    // Ensure that the publication exists and that 
    // it supports pull subscriptions.
    publication = new MergePublication();
    publication.Name = publicationName;
    publication.DatabaseName = publicationDbName;
    publication.ConnectionContext = publisherConn;

    if (publication.LoadProperties())
    {
        if ((publication.Attributes & PublicationAttributes.AllowPull) == 0)
        {
            publication.Attributes |= PublicationAttributes.AllowPull;
        }

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

        // Specify the Windows login credentials for the Merge Agent job.
        subscription.SynchronizationAgentProcessSecurity.Login = winLogin;
        subscription.SynchronizationAgentProcessSecurity.Password = winPassword;

        // Make sure that the agent job for the subscription is created.
        subscription.CreateSyncAgentByDefault = true;

        // Create the pull subscription at the Subscriber.
        subscription.Create();

        Boolean registered = false;

        // Verify that the subscription is not already registered.
        foreach (MergeSubscription existing
            in publication.EnumSubscriptions())
        {
            if (existing.SubscriberName == subscriberName
                && existing.SubscriptionDBName == subscriptionDbName
                && existing.SubscriptionType == SubscriptionOption.Pull)
            {
                registered = true;
            }
        }
        if (!registered)
        {
            // Register the local subscription with the Publisher.
            publication.MakePullSubscriptionWellKnown(
                subscriberName, subscriptionDbName,
                SubscriptionSyncType.Automatic,
                MergeSubscriberType.Local, 0);
        }
    }
    else
    {
        // Do something here if the publication does not exist.
        throw new ApplicationException(String.Format(
            "The publication '{0}' does not exist on {1}.",
            publicationName, publisherName));
    }
}
catch (Exception ex)
{
    // Implement the appropriate error handling here.
    throw new ApplicationException(String.Format(
        "The subscription to {0} could not be created.", publicationName), ex);
}
finally
{
    subscriberConn.Disconnect();
    publisherConn.Disconnect();
}

This example creates a pull subscription to a merge publication without creating an associated agent job and subscription metadata in MSsubscription_properties. The Windows account credentials used to create the Merge Agent job are passed at runtime.

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

//Create connections to the Publisher and Subscriber.
ServerConnection subscriberConn = new ServerConnection(subscriberName);
ServerConnection publisherConn = new ServerConnection(publisherName);

// Create the objects that we need.
MergePublication publication;
MergePullSubscription subscription;

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

    // Ensure that the publication exists and that 
    // it supports pull subscriptions.
    publication = new MergePublication();
    publication.Name = publicationName;
    publication.DatabaseName = publicationDbName;
    publication.ConnectionContext = publisherConn;

    if (publication.LoadProperties())
    {
        if ((publication.Attributes & PublicationAttributes.AllowPull) == 0)
        {
            publication.Attributes |= PublicationAttributes.AllowPull;
        }

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

        // Specify that an agent job not be created for this subscription. The
        // subscription can only be synchronized by running the Merge Agent directly.
        // Subscripition metadata stored in MSsubscription_properties will not
        // be available and must be specified at run time.
        subscription.CreateSyncAgentByDefault = false;

        // Create the pull subscription at the Subscriber.
        subscription.Create();

        Boolean registered = false;

        // Verify that the subscription is not already registered.
        foreach (MergeSubscription existing
            in publication.EnumSubscriptions())
        {
            if (existing.SubscriberName == subscriberName
                && existing.SubscriptionDBName == subscriptionDbName
                && existing.SubscriptionType == SubscriptionOption.Pull)
            {
                registered = true;
            }
        }
        if (!registered)
        {
            // Register the local subscription with the Publisher.
            publication.MakePullSubscriptionWellKnown(
                subscriberName, subscriptionDbName,
                SubscriptionSyncType.Automatic,
                MergeSubscriberType.Local, 0);
        }
    }
    else
    {
        // Do something here if the publication does not exist.
        throw new ApplicationException(String.Format(
            "The publication '{0}' does not exist on {1}.",
            publicationName, publisherName));
    }
}
catch (Exception ex)
{
    // Implement the appropriate error handling here.
    throw new ApplicationException(String.Format(
        "The subscription to {0} could not be created.", publicationName), ex);
}
finally
{
    subscriberConn.Disconnect();
    publisherConn.Disconnect();
}

This example creates a pull subscription to a merge publication that can be synchronized over the Internet using Web synchronization. The Windows account credentials used to create the Merge Agent job are passed at runtime. For more information, see How to: Configure Web Synchronization for Merge Replication (RMO Programming)

// Define the Publisher, publication, and databases.
string publicationName = "AdvWorksSalesOrdersMerge";
string publisherName = publisherInstance;
string subscriberName = subscriberInstance;
string subscriptionDbName = "AdventureWorksReplica";
string publicationDbName = "AdventureWorks";
string hostname = @"adventure-works\garrett1";
string webSyncUrl = "https://" + publisherInstance + "/WebSync/replisapi.dll";

//Create connections to the Publisher and Subscriber.
ServerConnection subscriberConn = new ServerConnection(subscriberName);
ServerConnection publisherConn = new ServerConnection(publisherName);

// Create the objects that we need.
MergePublication publication;
MergePullSubscription subscription;

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

    // Ensure that the publication exists and that 
    // it supports pull subscriptions and Web synchronization.
    publication = new MergePublication();
    publication.Name = publicationName;
    publication.DatabaseName = publicationDbName;
    publication.ConnectionContext = publisherConn;

    if (publication.LoadProperties())
    {
        if ((publication.Attributes & PublicationAttributes.AllowPull) == 0)
        {
            publication.Attributes |= PublicationAttributes.AllowPull;
        }
        if ((publication.Attributes & PublicationAttributes.AllowWebSynchronization) == 0)
        {
            publication.Attributes |= PublicationAttributes.AllowWebSynchronization;
        }

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

        // Specify the Windows login credentials for the Merge Agent job.
        subscription.SynchronizationAgentProcessSecurity.Login = winLogin;
        subscription.SynchronizationAgentProcessSecurity.Password = winPassword;

        // Enable Web synchronization.
        subscription.UseWebSynchronization = true;
        subscription.InternetUrl = webSyncUrl;

        // Specify the same Windows credentials to use when connecting to the
        // Web server using HTTPS Basic Authentication.
        subscription.InternetSecurityMode = AuthenticationMethod.BasicAuthentication;
        subscription.InternetLogin = winLogin;
        subscription.InternetPassword = winPassword;

        // Ensure that we create a job for this subscription.
        subscription.CreateSyncAgentByDefault = true;

        // Create the pull subscription at the Subscriber.
        subscription.Create();

        Boolean registered = false;

        // Verify that the subscription is not already registered.
        foreach (MergeSubscription existing
            in publication.EnumSubscriptions())
        {
            if (existing.SubscriberName == subscriberName
                && existing.SubscriptionDBName == subscriptionDbName
                && existing.SubscriptionType == SubscriptionOption.Pull)
            {
                registered = true;
            }
        }
        if (!registered)
        {
            // Register the local subscription with the Publisher.
            publication.MakePullSubscriptionWellKnown(
                subscriberName, subscriptionDbName,
                SubscriptionSyncType.Automatic,
                MergeSubscriberType.Local, 0);
        }
    }
    else
    {
        // Do something here if the publication does not exist.
        throw new ApplicationException(String.Format(
            "The publication '{0}' does not exist on {1}.",
            publicationName, publisherName));
    }
}
catch (Exception ex)
{
    // Implement the appropriate error handling here.
    throw new ApplicationException(String.Format(
        "The subscription to {0} could not be created.", publicationName), ex);
}
finally
{
    subscriberConn.Disconnect();
    publisherConn.Disconnect();
}

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.