Component Services for .NET II of V...

Part II: Practicalities - creating and consuming a serviced component (part one).

Knowledge assumed: VB.NET, VS.NET, component/ n-tier development, transactions, Part I

Date: September 12, 2004

Introduction

As introduced in Part I of this series of 5 articles (originally planned as 4!) the topic of component services is about creating enterprise applications that need to be secure, reliable, available, efficient and scalable with the minimum developer effort. In Part I we introduced the necessary background theory and in this article we shall get to the practicalities of creating and consuming a serviced component, in particular looking at performing the following necessary steps:

Coding the serviced component in VS/VB.NET
Creating the corresponding strongly named assembly
Registering the serviced component in the COM+ catalog
Configuring the serviced component via the component services administrative tool

Creating and consuming a serviced component

Here are the steps we must follow:

Create a class that inherits from the ServicedComponent class.
Assign a strong name to create a strongly named assembly.
Install the assembly in to the COM+ catalog.
Install the strongly named assembly into the Global Assembly Cache (GAC) (recommended)

When these steps have been completed the serviced component will be available to both application programmers to utilise in their applications and to system administrators to configure via the Component Services administrative tool.

You will note above that step 4 is part of the recommended approach, for the number of benefits the GAC brings to the equation, but is not essential to being able to consume the component. We'll now go through 1 to 3.

1. Create a class that inherits from the ServicedComponent class

We shall create a simple class to facilitate database access at the same time introducing how to set basic assembly level attributes. I should acknowledge at this point that the code is based on the example presented in Mike Gunderloy's 'Developing XML WebServices and Server Components with VB.NET and the .NET Framework' which I can recommend if you're after a more detailed explanation of COM+ and/ or you are actively pursuing Microsoft Certification in .NET.

Create a new VS.NET solution.

Add a new VB.NET class library project. Rename the default class1.vb to NorthwindSC.vb.

Add a reference to System.EnterpriseServices.

Replace the code as follows:

Imports System
Imports System.Data
Imports System.Data.SqlClient
Imports System.EnterpriseServices

  Public Class NorthwindSC
    Inherits ServicedComponent

    Private sqlcnn As SqlConnection
    Private sqlda As SqlDataAdapter
    Private ds As DataSet

    Public Sub New()
      'create a connection to the Northwind SQL Server database
      sqlcnn = New SqlConnection("data source=(local); initial catalog=Northwind;" & _
        "integrated security=SSPI")
    End Sub

    'executes a SELECT query and returns the results in a DataSet object
    Public Function ExecuteQuery(ByVal strQuery As String) As DataSet
      'create a SqlDataAdapter object to talk to the database
      sqlda = New SqlDataAdapter(strQuery, sqlcnn)

      'create a DataSet object to hold the results
      ds = New DataSet

      'fill the DataSet object
      sqlda.Fill(ds, "Results")

      ExecuteQuery = ds
    End Function

    'this method updates the database with the changes in a DataSet object
    Public Function UpdateData(ByVal ds As DataSet) As Integer
      'update the database and return the result
      Dim sqlcb As SqlCommandBuilder = New SqlCommandBuilder(sqlda)
      UpdateData = sqlda.Update(ds.Tables("Results"))
    End Function
End Class

Note you should ensure the connection string listed above is appropriate to your system and set up.

Open the AssemblyInfo.vb file in the project and add the following directive:

Imports System.EnterpriseServices

Add assembly level attributes as follows to the end of the file:

<Assembly: ApplicationName("Northwind Data Application")>
<Assembly: Description("Retrieve and Update data from the Northwind database")>
<Assembly: ApplicationActivation(ActivationOption.Library)>

Thus we've created a serviced component that we've specified should be activated in Library mode. This is actually the default but it's always better to define such things explicitly.

Note that VS.NET uses a separate file named AssemblyInfo.vb to store assembly-level attributes. For a single class library the assembly level attributes can be placed in the same class file if preferable, though for clarity and extensibility it remains best practice to use the separate file.

2. Assign a strong name to create a strongly named assembly

A serviced component must be signed with a strong name before it can be registered in the COM+ catalog. I'll assume the reader is familiar with the concepts of strong names, public-private key encryption and use of the strong name tool (sn.exe).

We need to create a strong name and then modify our component to associate this strong name with its assembly. We must regenerate the dll to do this as signing with a strong name is part of the assembly creation process.

Launch the VS.NET command prompt. Navigate to where your solution resides and generate a pair of public/ private keys as follows:

sn –k NorthwindSC.snk

Open the AssemblyInfo.vb file of the corresponding project and add an AssemblyKeyFile attributes as follows:

<Assembly: AssemblyKeyFile("..\..\..\northwindSC.snk")>

This will be correct if you place your .snk in the project root. Otherwise you shoud amend accordingly.

Build the file and a strong name is assigned to the file based on the specified keyfile.

3. Install the assembly in to the COM+ catalog.

Now the assembly has been assigned a strong name it can be installed in the catalog – necessary for the component to use any of the COM+ services. This registration process involves retrieving all the necessary runtime information (mainly specified in the form of attributes) from the class library and copying it into the COM+ catalog.

As COM+ doesn't recognise .NET managed components this is the point where we must expose the component via COM. The .NET class EnterpriseServices.RegistrationHelper is available to assist, allowing us to perform the following steps:

use the RegistrationServices.RegisterAssembly() method to register the assembly in the registry.
generate a COM type library from the assembly using the TypeLibConveter.ConvertAssemblyToTypeLib() method.
register the type library by using the LoadTypeLibrary() method.
use the COM+ admin API to configure COM+ based on the information stored in the type library.

Alternatively .NET provides 2 wrappers on top of the class to make life even easier for you that do not require you to write any code:

dynamic or lazy registration – the registration of a serviced component is delayed until the component is first used. At this point the CLR registers the assembly and type library and configures the COM+ catalog. Dynamic registration occurs only once for a particular version of an assembly.

manual registration – the .NET services installation tool (regsvcs.exe) allows manual installation from the command line.

Key pertinent points regarding these approaches are:

Assemblies placed in the GAC require manual registration.
Any serviced component called by COM clients must be registered manually.
Lazy registration does not allow you to trap registration errors before the component is actually used.

We'll use manual registration in this instance:

Launch the VS.NET command prompt. Locate the project's ddl file directory. Install the assembly to the COM+ catalog as follows:

regsvcs dataSC.dll

The serviced component is now installed in the COM+ catalog and can be instantiated by client programs or administered through the component services administration tool.

If you haven't used it before take a look at the component services administrative tool now and familiarise yourself with its features. For example, if you view the properties of the newly added application and look at the activation section you'll see it is correctly configured as a library application, as we specified in the code. Further if you view the properties of the component itself you see tabs such as transactions and activation. Familiarise yourself with the options.

In the next article we'll look at some of these configuration options in further detail. These options can also be specified at the method level but these are not configurable at the administrative tool level by default – we'll see how to enable such configuration options next. If you look at the interfaces of your component in the tool you'll find one named _NorthwindSC. Although you didn’t define an interface one has been added to the component for you. However, if you expand the methods node you won’t see your methods listed there.

Conclusion

In this article we made our way half way through the process of creating and consuming a serviced component. In the next article we'll complete this process looking at:

Configuring the serviced component in code (creating interfaces that are visible to COM)
Installing the component in the GAC
Consuming the component

References

.NET SDK

Developing XML WebServices and Server Components with VB.NET and the .NET Framework
Mike Gunderloy
Que

References

.NET SDK

Developing XML WebServices and Server Components with VB.NET and the .NET Framework
Mike Gunderloy
Que