How to: View and Modify Publisher and Distributor Properties (RMO Programming)

You can programmatically view and modify Publisher and Distributor properties by using Replication Management Objects (RMO).

To view and modify Distributor properties

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

2. Create an instance of the ReplicationServer class. Pass the ServerConnection object from step 1.

3. (Optional) Check the IsDistributor property to verify that the currently connected server is a Distributor.

4. Call the Load method to get the properties from the server.

5. (Optional) To change properties, set a new value for one or more of the Distributor properties that can be set on the ReplicationServer object.

6. (Optional) If the CachePropertyChanges property on the ReplicationServer object is set to true, call the CommitPropertyChanges method to commit the changes to the server.

To view and modify distribution database properties

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

2. Create an instance of the DistributionDatabase class. Specify the name property and pass the ServerConnection object from step 1.

3. Call the LoadProperties method to get the properties from the server. If this method returns false, the database with the specified name does not exist on the server.

4. (Optional) To change properties, set a new value for one of the DistributionDatabase properties that can be set.

5. (Optional) If the CachePropertyChanges property on the DistributionDatabase object is set to true, call the CommitPropertyChanges method to commit the changes to the server.

To view and modify Publisher properties

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

2. Create an instance of the DistributionPublisher class. Specify the Name property and pass the ServerConnection object from step 1.

3. (Optional) To change properties, set a new value for one of the DistributionPublisher properties that can be set.

4. (Optional) If the CachePropertyChanges property on the DistributionPublisher object is set to true, call the CommitPropertyChanges method to commit the changes to the server.

To change the password for the administrative connection from the Publisher to the Distributor

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

2. Create an instance of the ReplicationServer class.

3. Set the ConnectionContext property to the connection created in step 1.

4. Call the Load method to get the properties of the object.

5. Call the ChangeDistributorPassword method. Pass the new password value for the password parameter.

   Security Note:
   When possible, prompt users to enter security credentials at runtime. If you must store credentials, use the cryptographic services provided by the Microsoft Windows .NET Framework.

6. (Optional) Perform the following steps to change the password at each remote Publisher that uses this Distributor:

   1. Create a connection to the Publisher by using the ServerConnection class.
   2. Create an instance of the ReplicationServer class.
   3. Set the ConnectionContext property to the connection created in step 6a.
   4. Call the Load method to get the properties of the object.
   5. Call the ChangeDistributorPassword method. Pass the new password value from Step 5 for the password parameter.

Example

This example shows how to change Distribution and distribution database properties.

Security Note:
To avoid storing credentials in the code, the new Distributor password is supplied at runtime.

// Set the Distributor and distribution database names.
string distributionDbName = "distribution";
string distributorName = publisherInstance;

ReplicationServer distributor;
DistributionDatabase distributionDb;

// Create a connection to the Distributor using Windows Authentication.
ServerConnection conn = new ServerConnection(distributorName);

try
{
    // Open the connection. 
    conn.Connect();

    distributor = new ReplicationServer(conn);

    // Load Distributor properties, if it is installed.
    if (distributor.LoadProperties())
    {
        // Password supplied at runtime.
        distributor.ChangeDistributorPassword(password);
        distributor.AgentCheckupInterval = 5;

        // Save changes to the Distributor properties.
        distributor.CommitPropertyChanges();
    }
    else
    {
        throw new ApplicationException(
            String.Format("{0} is not a Distributor.", publisherInstance));
    }

    // Create an object for the distribution database 
    // using the open Distributor connection.
    distributionDb = new DistributionDatabase(distributionDbName, conn);

    // Change distribution database properties.
    if (distributionDb.LoadProperties())
    {
        // Change maximum retention period to 48 hours and history retention 
        // period to 24 hours.
        distributionDb.MaxDistributionRetention = 48;
        distributionDb.HistoryRetention = 24;

        // Save changes to the distribution database properties.
        distributionDb.CommitPropertyChanges();
    }
    else
    {
        // Do something here if the distribution database does not exist.
    }
}
catch (Exception ex)
{
    // Implement the appropriate error handling here. 
    throw new ApplicationException("An error occured when changing Distributor " +
        " or distribution database properties.", ex);
}
finally
{
    conn.Disconnect();
}

' Set the Distributor and distribution database names.
Dim distributionDbName As String = "distribution"
Dim distributorName As String = publisherInstance

Dim distributor As ReplicationServer
Dim distributionDb As DistributionDatabase

' Create a connection to the Distributor using Windows Authentication.
Dim conn As ServerConnection = New ServerConnection(distributorName)

Try
    ' Open the connection. 
    conn.Connect()

    distributor = New ReplicationServer(conn)

    ' Load Distributor properties, if it is installed.
    If distributor.LoadProperties() Then
        ' Password supplied at runtime.
        distributor.ChangeDistributorPassword(password)
        distributor.AgentCheckupInterval = 5

        ' Save changes to the Distributor properties.
        distributor.CommitPropertyChanges()
    Else
        Throw New ApplicationException( _
            String.Format("{0} is not a Distributor.", publisherInstance))
    End If

    ' Create an object for the distribution database 
    ' using the open Distributor connection.
    distributionDb = New DistributionDatabase(distributionDbName, conn)

    ' Change distribution database properties.
    If distributionDb.LoadProperties() Then
        ' Change maximum retention period to 48 hours and history retention 
        ' period to 24 hours.
        distributionDb.MaxDistributionRetention = 48
        distributionDb.HistoryRetention = 24

        ' Save changes to the distribution database properties.
        distributionDb.CommitPropertyChanges()
    Else
        ' Do something here if the distribution database does not exist.
    End If
Catch ex As Exception
    ' Implement the appropriate error handling here. 
    Throw New ApplicationException("An error occured when changing Distributor " + _
        " or distribution database properties.", ex)
Finally
    conn.Disconnect()
End Try

See Also

Tasks

How to: Configure Publishing and Distribution (RMO Programming)
How to: Disable Publishing and Distribution (RMO Programming)
How to: View and Modify Publisher and Distributor Properties (Replication Transact-SQL Programming)

Concepts

Programming with Replication Management Objects
Programming with Replication Management Objects

Other Resources

Configuring Distribution

Help and Information

Getting SQL Server 2005 Assistance