Step by Step
Listing 1, page 28, shows the Visual Basic .NET code that implements the Windows Form for the synchronization application. (For readability, I removed all the Visual Studio Designer-generated code that represents the UI objects on the Windows Form.) Let's walk through the process of building this sample application, including creating a Visual Studio .NET project, coding the application in Visual Basic .NET, and deploying the application.
Setting up the project. The main complicating factor of using the Merge control in a .NET application is that the Merge control is unmanaged code. To program against the control, you must use a System.Interop managed interface that the .NET Framework requires when accessing unmanaged code from managed environments. Fortunately, when you use Visual Studio .NET to build this sample, the development environment automatically generates the required System.Interop wrappers for this unmanaged ActiveX control.
After creating a new Visual Basic Windows Forms application project in Visual Studio .NET, you add to the project references for both the replication Merge and Error controls. (When SQL Server 2000 is installed, the ActiveX controls are also installed and registered with the Windows OS.) To add the references, click Add Reference from the Project menu, then in the Add Reference menu, select Microsoft SQL Merge Control 8.0 and Microsoft SQL Replication Errors 8.0 from the list of available COM components.
Building the UI. After setting up the project, you need to lay out the form by adding the following eight Windows Forms controls:
- cmdSync - a Button control for synchronizing the subscription
- barSyncProgress - a ProgressBar control that shows the synchronization progress
- txtPublisherServer - a TextBox control that specifies the Publisher
- txtPublicationDB - a TextBox control that specifies the publication database
- txtSubscriberServer - a TextBox control that specifies the Subscriber
- txtSubscriptionDB - a TextBox control that specifies the subscription database
- cmdCancel - a Button control to cancel the synchronization process
- cmdClose - a Button control to close the application
Setting the control properties. When you're laying out the form, Visual Studio automatically creates in the form's code behind page the code that implements the UI components. To this Visual Basic .NET code in the project, you must add the synchronization code that Listing 1 shows. When referencing objects in the code, you would normally have to fully qualify each object's name with the object's namespace reference. But you can save a lot of code by adding Imports directives that reference these namespaces, as the code at callout A in Listing 1 shows.
At callout B, the code instantiates a SQLMerge object and a SQLReplError object. You use the WithEvents keyword to enable callback functionality on the SQLMerge object. The code at callout C defines a handler for this callback functionality, which I'll explain in a moment. Note that you need to declare the SQLMerge object at the module level if you want to use the callback functionality.
In the sample application, the code that synchronizes the subscription is in the cmdSync_Click method and executes in response to the cmdSync button's Click event. In this method, you define the SQLMerge object properties for the pull subscription, as the code at callout D shows.
Activating the Merge Agent. After setting the Merge Agent properties through the SQLMerge object, you need to tell the agent to synchronize the subscription. You do that by using the SQLMerge object's Initialize, Run, and Terminate methods, as the code at callout E shows. In Visual Basic .NET, you should call these methods within a Try/Catch statement to properly handle any errors that occur.
Handling errors. Replication provides a separate error-handling control that you can use to give users detailed error information. The Microsoft SQL Replication Errors 8.0 control implements both a SQLReplError class and a SQLReplErrors collection. When a replication error occurs, the SQLMerge object adds a reference to the error collection in the ErrorRecords property. The code at callout F in Listing 1 shows how to handle replication errors that occur during synchronization and how to iterate through the errors in the collection. This section of code checks the SQLMerge object for any SQLReplError objects in the ErrorRecords collection, which would indicate that errors occurred during the synchronization process. If any errors exist, the code queries each error and uses the information to build error messages that it displays in the UI.
Using the Status event. The replication ActiveX controls provide information about the synchronization process's progress and result by using a callback function known as the Status event. This functionality provides both a progress bar that shows the percent-complete value during long-running processes, as Figure 2 shows, and a message string that describes the result of the synchronization process, as Figure 3 shows. To implement the Status event in a managed-code environment such as Visual Basic .NET, you need to be running SQL Server 2000 Service Pack 3 (SP3).
Callout G in Listing 1 shows the method that handles the Status event. As I mentioned earlier, to use the Status event, you need to declare myMergeObj at the module level by using the WithEvents keyword. This routine returns a SUCCESS code to the Merge control. Setting the return value of this event handler to CANCEL will cancel the synchronization process. Calling the DoEvents method updates the progress bar. Note that you need one more line of code to make the event handler at callout G work; callout C shows the code that adds a handler for the Status event.
Deploying the application. After coding the application, you compile it into a .NET executable by using Visual Studio .NET's build functionality. In addition to the executable, Visual Studio .NET creates two .dll files—Interop.SQLMERGXLib.dll and Interop.REPLERRXLib.dll—which contain the Merge and Error ActiveX controls and their managed-code wrappers. To deploy this application, simply copy these three files into the same directory on a computer that's running SQL Server 2000.
Customization and Control
Replication lets you distribute and synchronize data across your enterprise. And merge replication, in particular, is an ideal solution when you need to distribute copies of data to many users and for applications in which users modify data in a disconnected and highly autonomous state. When you want to let users have some control over replication, such as when to synchronize their copies of the data with a central Publisher, the replication ActiveX controls provide a powerful programmatic tool.
End of Article
Prev. page
1
[2]
next page -->
