How to: Configure a Subscription to Use Web Synchronization (RMO Programming)

New: 5 December 2005

The procedure in this topic is the third step in configuring Web synchronization for merge replication. You perform this step after you enable the publication and configure the computer that is running Microsoft Internet Information Services (IIS). For an overview of the configuration process, see How to: Configure Web Synchronization for Merge Replication (RMO Programming). When you configure a subscription to use Web synchronization for Subscribers that can only connect to the Publisher through HTTP, you must properly configure the Publication. For more information, see How to: Configure a Publication to Allow for Web Synchronization (RMO Programming). After you complete the procedures in this topic, synchronize the subscription you have created. For more information, see How to: Synchronize a Pull Subscription (RMO Programming).

This topic describes the parameters that are required by Web synchronization. For more information about how to create pull subscriptions, see How to: Create a Pull Subscription (RMO Programming).

Important

The URL of the Web server that is used for Web synchronization (such as https://server.domain.com/directory/replisapi.dll) specifies the location of replisapi.dll. If the server is configured to use a port other than the default port 443 for Secure Sockets Layer (SSL), you must also supply the port: https://server.domain.com:PortNumber/directory/replisapi.dll. The name of the server in the URL must be the same as the name that was used when the certificate was created. For example, on an intranet, you might be able to access a Web server through https://server/. However, if the fully qualified name (such as https://server.domain.com/) was used when the certificate was created, you must use this fully qualified name in the URL (https://server.domain.com/directory/replisapi.dll).

To configure a subscription to use Web synchronization

1. Create connections to 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.

3. (Optional) If the subscription database does not exist, create the database by using the SQL Server Management Objects (SMO) Database class. For more information, see Creating, Altering, and Removing Databases.

4. Create an instance of the MergePullSubscription class.

5. Set the following subscription properties:

   • The ServerConnection to the Subscriber that was 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.

   • Value of true for UseWebSynchronization.

   • Location of the Web server that hosts Web synchronization for InternetUrl.

   • Login and password for the Windows account under which the Merge Agent runs at the Subscriber for the Login and Password fields of SynchronizationAgentProcessSecurity, respectively. This account is also used when the Merge Agent makes connections to the local Subscriber.

     Note

     When the publication is created by a member of the sysadmin fixed server role, you do not have to set SnapshotGenerationAgentProcessSecurity. For more information, see Replication Agent Security Model.

   • Value of 0 for InternetSecurityMode and also values for InternetLogin and InternetPassword when HTTP Basic Authentication is used to access the Web server. We recommend that you use this authentication method for Web synchronization. For more information, see Securing Replication Over the Internet.

6. Call the Create method.

7. Using the instance of MergePublication from step 2, call the MakePullSubscriptionWellKnown method to register the pull subscription with the Publisher.

To configure a subscription to use Web synchronization for Subscribers that can only connect to the Publisher through a Web server using HTTP

1. Create a connection to the Subscriber by using the ServerConnection class.

2. (Optional) If the subscription database does not exist, create the database by using the SMO Database class. For more information, see Creating, Altering, and Removing Databases.

3. Create an instance of the MergePullSubscription class.

4. Set the following subscription properties:

   • The ServerConnection 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.

   • A value of Anonymous for SubscriberType.

   • Value of true for UseWebSynchronization.

   • Location of the Web server that hosts Web synchronization for InternetUrl.

   • Login and password for the Windows account under which the Merge Agent runs at the Subscriber for the Login and Password fields of SynchronizationAgentProcessSecurity, respectively. This account is also used when the Merge Agent makes connections to the local Subscriber.

     Note

     When the publication is created by a member of the sysadmin fixed server role, you do not have to set SnapshotGenerationAgentProcessSecurity. For more information, see Replication Agent Security Model.

   • Value of 0 for InternetSecurityMode and also values for InternetLogin and InternetPassword when HTTP Basic Authentication is used to access the Web. We recommend that you use this authentication method for Web synchronization. For more information, see Securing Replication Over the Internet.

5. Call the Create method.

Example

The following example creates a subscription that is synchronized with the Publisher using Web synchronization.

// 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();
}

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

'Create connections to the Publisher and Subscriber.
Dim subscriberConn As ServerConnection = New ServerConnection(subscriberName)
Dim publisherConn As ServerConnection = New ServerConnection(publisherName)

' Create the objects that we need.
Dim publication As MergePublication
Dim subscription As MergePullSubscription

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() Then
        If (publication.Attributes And PublicationAttributes.AllowPull) = 0 Then
            publication.Attributes = publication.Attributes _
            Or PublicationAttributes.AllowPull
        End If
        If (publication.Attributes And PublicationAttributes.AllowWebSynchronization) = 0 Then
            publication.Attributes = publication.Attributes _
            Or PublicationAttributes.AllowWebSynchronization
        End If

        ' 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
        subscription.CreateSyncAgentByDefault = True

        ' 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

        ' Create the pull subscription at the Subscriber.
        subscription.Create()

        Dim registered As Boolean = False

        ' Verify that the subscription is not already registered.
        For Each existing As MergeSubscription In _
        publication.EnumSubscriptions()
            If existing.SubscriberName = subscriberName Then
                registered = True
            End If
        Next
        If Not registered Then
            ' Register the local subscription with the Publisher.
            publication.MakePullSubscriptionWellKnown( _
             subscriberName, subscriptionDbName, _
             SubscriptionSyncType.Automatic, _
             MergeSubscriberType.Local, 0)
        End If
    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))
    End If
Catch ex As Exception
    ' 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()
End Try

This example creates a subscription that is synchronized with the Publisher using Web synchronization for a Subscriber that can only connect to the Publisher through a Web server using HTTP.

// The publication must support anonymous Subscribers, pull 
// subscriptions, and Web synchronization.
// 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 the Subscriber connection.
ServerConnection conn = new ServerConnection(subscriberName);

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

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

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

    // Specify an anonymous Subscriber type since we can't 
    // register at the Publisher with a direct connection.
    subscription.SubscriberType = MergeSubscriberType.Anonymous;

    // 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();
}
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
{
    conn.Disconnect();
}

' The publication must support anonymous Subscribers, pull 
' subscriptions, and Web synchronization.
' Define the Publisher, publication, and databases.
Dim publicationName As String = "AdvWorksSalesOrdersMerge"
Dim publisherName As String = publisherInstance
Dim subscriberName As String = subscriberInstance
Dim subscriptionDbName As String = "AdventureWorksReplica"
Dim publicationDbName As String = "AdventureWorks"
Dim hostname As String = "adventure-works\\garrett1"
Dim webSyncUrl As String = "https://" + publisherInstance + "/WebSync/replisapi.dll"

'Create the Subscriber connection.
Dim conn As ServerConnection = New ServerConnection(subscriberName)

' Create the objects that we need.
Dim subscription As MergePullSubscription

Try
    ' Connect to the Subscriber.
    conn.Connect()

    ' Define the pull subscription.
    subscription = New MergePullSubscription()
    subscription.ConnectionContext = conn
    subscription.PublisherName = publisherName
    subscription.PublicationName = publicationName
    subscription.PublicationDBName = publicationDbName
    subscription.DatabaseName = subscriptionDbName
    subscription.HostName = hostname

    ' Specify an anonymous Subscriber type since we can't 
    ' register at the Publisher with a direct connection.
    subscription.SubscriberType = MergeSubscriberType.Anonymous

    ' 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()
Catch ex As Exception
    ' Implement the appropriate error handling here.
    Throw New ApplicationException(String.Format( _
         "The subscription to {0} could not be created.", publicationName), ex)
Finally
    conn.Disconnect()
End Try

See Also

Tasks

How to: Create a Pull Subscription (RMO Programming)

Concepts

How to: Configure Web Synchronization for Merge Replication (Replication Transact-SQL Programming)

Other Resources

Web Synchronization for Merge Replication

Help and Information

Getting SQL Server 2005 Assistance