Using Designer with the Package for Microsoft .NET

Overview

With the Package for Microsoft .NET installed, you can use the webMethods for Microsoft Plug-in to scan existing .NET assemblies to determine what methods they contain and then import the methods into Designer. In Designer, you can create services that call those methods. Once a .NET service exists within Designer, it can become part of a flow, just like any other service.

To take advantage of this feature, you must have the Microsoft .NET Framework, which includes the Common Language Runtime (CLR) installed on the same computer as the instance of Integration Server to which Designer is connected. In addition, the location of the .NET assembly must be known to Integration Server. For example, assume that you have used Designer to create the service addInt to call the addInt method in mathAssembly.dll. When you invoke the addInt service on Integration Server, the service calls the addInt method through the CLR.

Figure 1. A service calls a .NET method

Using Designer, you can perform the following actions:

You can do this... Described here...
Import .NET assembly methods into Designer Importing .NET Methods into Designer.
Modify information about a .NET method associated with a service Configuring .NET Assembly Information.
Manage the way the CLR maintains instance data Managing Class Lifetimes.

Importing .NET Methods into Designer

About this task

You can import methods from Microsoft .NET assemblies and use them to create .NET services. webMethods services can consume these .NET services.

Tip: From a practical standpoint, it is easiest to import and maintain all .NET services from an assembly into the same folder.

To create a .NET service from a .NET method using Designer

Procedure

  1. The .NET Common Language Runtime (CLR) should start automatically, but if it is not yet loaded, use Integration Server Administrator to start it.

    For more information, see Starting and Stopping the Microsoft .NET CLR.

  2. From Designer, go to File > New > .NET Service.
  3. Select the folder in which the services are to be created and click Next.
  4. In the Create a New .NET Service dialog box, locate a .NET assembly on the path where the CLR can access it.

    This dialog box displays the white-listed directories. For more information on white-listed directories, see Specifying white-listed directories.The only files displayed in this dialog box are assembly DLLs or EXEs. You can select multiple .NET assemblies for importing.

  5. After you have selected assemblies, click Next.
  6. In the Select Specific .NET services dialog box, select the methods you want to import into Designer. By default, all methods in all selected assemblies are selected. You can select or clear whole assemblies, whole classes, or individual methods as needed.
  7. Click Finish. Designer creates a service for each method and places it in the specified folder.
    Note: For assemblies that are not located in the same windows domain or on the same machine as the CLR, the CLR may fail to load an assembly and issue a security error if the assembly was compiled with the unsafe option or if user permissions for the remote directory do not permit access. To resolve either condition, copy the assembly to the machine where the CLR resides, set directory permissions appropriately, or configure a trust relationship between the domains.

Results

You can view the variables for the resulting service in the Input/Output tab of the editor. In addition to the variables supported by a specific method, there are variables that are part of each .NET service.

Input Variables

The trace variable allows you to perform method invocation tracing for a specific service. For more information, see Method Invocation Tracing.

The domain name mentions the name of the domain from where you want this method to be invoked.

The marshallingType variable identifies the marshalling type to be used for a specific service, as described in Marshalling Data. To use a reference ID to marshall data, choose refid. To actually send data in the form of an XML file, choose xml.

The instanceID variable identifies a particular session for object instances using a Session class lifetime, as described in Managing Class Lifetimes. On the first invocation, the instanceID variable should be set to a value zero. If a Session lifetime is configured for an object instance, on subsequent invocations, you should set the variable to the instance ID returned from the first invocation of the method.

Output Variables

As mentioned in Input Variables instanceID is present as an output variable. This variable identifies the instance of the session object and can be used as input for subsequent invocations of the object.

A return variable is also present. The return variable contains the value returned by the method upon completion of its invocation.

Importing COM Objects into Designer

The Microsoft Type Library Importer (TLBIMP) generates a Primary Interop Assembly, which is a .NET assembly, from a COM object. Once an assembly is generated using TLBIMP, you can import the methods from that assembly into Designer as you would any .NET assembly.

In broad overview, these are the steps to import COM objects into Designer as services:

  1. If you have not already done so, use the regsvr32 command to register the COM object on the computer where you will make the conversion.
  2. Use TLBIMP to generate the assembly, as in this simple example: 
    tlbimp COM_object_name /out:output_name
  3. Use the output file as though it were a .NET assembly and import it into Designer, as described in Importing .NET Methods into Designer.

Configuring .NET Assembly Information

About this task

When you create a service to call a Microsoft .NET method, Integration Server stores information needed by the .NET CLR to load the method into its processing space. If you change the location or name of the .NET assembly in which the method resides, you need to use Designer to modify that information; otherwise, any attempt to call that method from Integration Server will fail.

Information about a particular .NET method resides with the service you have created to call it. In Designer, you can see this information in the .NET Properties tab for the specified service.

Note: When you create multiple .NET services from an assembly, as described in Importing .NET Methods into Designer, all of those services share information about the assembly. If you change shared information for one .NET service, it is changed for all.

The Shared Properties panel of the .NET Properties tab consists of information that is common to all .NET services created from the same assembly:

Property Description
Domain Name The name of the application domain in which the service is to run. Editable.
Assembly Path The location of the directory that holds the .NET assembly in which the method called by this service resides. Editable. Changing the assembly path of a .NET service applies to all the .NET services in the assembly.
Assembly Name The name of the .NET assembly in which the method called by this service resides. Editable. Changing the assembly name of a .NET service applies to all the .NET services in the assembly.
Domain Configuration File The configuration file associated with the domain. The file must be located in the Assembly Path. Enter only the file name. For more information about domain configuration file, see Managing Domain Configuration File
Class Name The fully qualified name of the class of which the method called by this service is a part. Not editable
Class Lifetime The lifetime setting assigned to the class that owns the method called by this service. Editable. For information about valid class lifetime settings, see Managing Class Lifetimes.
Class Timeout (mins) The timeout setting assigned to the class that owns the method called by this service. Valid only for a Session lifetime. Editable. See The Class Timeout Value.

Another property in the .NET Properties tab is unique to the specific .NET service:

Property Description
Method Name The name of the method called by this service.

To change information about a .NET method :

Procedure

  1. In the Navigation panel, double-click the service for which you want to change information about its associated .NET method.
  2. Click the .NET Properties tab to bring it to the front.
  3. Perform one or more of the following actions:
    To do this... Perform the following...
    Change the assembly path name In the Assembly Path field, type the new location of the directory that holds the .NET assembly in which the method resides.
    Change the assembly name In the Assembly Name field, type the new name of the .NET assembly in which the method resides.
    Change the domain name In the Domain Name field, type the new domain name.
    Change the domain configuration file In the Domain Configuration File field, type the name of the new domain configuration file.
  4. On the File menu, click Save.
  5. Stop and restart the CLR to clear the cache and make sure the correct assembly is loaded.

    For more information, see Starting and Stopping the Microsoft .NET CLR.

    You will see that these changes are applied to all .NET services that call methods in the same assembly.

  6. Go to Integration Server Administrator and reload the WmDotNet package.

Managing Domain Configuration File

The Domain Configuration File is typically used for any configurations associated with the domain, that need to be accessed at the time of service invocation. For example, the information required to access a database, or an input to the service, can be provided in the configuration file.

You must keep the domain configuration file in the same location as the assembly path. Also, enter only the name of the file. The domain configuration file is tightly associated with the particular domain. If you want to run the same service under the same domain with a different configuration file, you must first destroy the domain to remove association with the earlier configuration file. After destroying, recreate the domain, and associate another domain configuration file with the domain.

Ensure that the configuration file has a key named as WhitelistDirectories and that the white-listed directories are specified as value for the key. For more information on white-listed directories, see Specifying white-listed directories.

Important: Ensure that the configuration file exists before you create the application domain for the service.

Managing Class Lifetimes

.NET classes running on the CLR can maintain instance data, which are variables containing information used across multiple invocations of methods on the class. A class instance can maintain instance data according to one of four Class Lifetime settings, described in the following table. All .NET services associated with a class have the same lifetime. When you change the class lifetime for a particular .NET service, Designer modifies the lifetimes of all services associated with the same class.

In Designer, you can manage the class lifetime for a particular .NET service in the .NET Properties tab for that service. The Class Lifetime property has the following valid settings:

Lifetime Setting Description
Global The Package for Microsoft .NET creates a single instance of the class, or object, which has an unlimited lifetime. The class shares instance data among all sessions. Use this setting where it is appropriate to gather data to be retrieved by multiple users. You can create only one instance of a global object of a given type.
Session The Package for Microsoft .NET creates a separate object for each user. The object exists until the user session is closed or until the object times out. The default is three minutes. See The Class Timeout Value.
Single-Use The Package for Microsoft .NET creates and destroys an object each time a .NET service calls a method in the class. Data may be kept during the lifetime of the object.
Static The .NET service calls a method that does not require any session data to be kept. All methods of the class are static and the Package for Microsoft .NET does not create an object.
Note: If multiple services are using a given global object or a session object at the same time, those objects need to be thread safe.

Use the Static lifetime setting only for static methods.

Modifying Class Lifetime

About this task

The following procedure describes how to modify the Class Lifetime setting for a .NET service.

To modify the Class Lifetime for a .NET service

Procedure

  1. In the Navigation panel, double-click the service for which you want to change the Class Lifetime setting.
  2. Click the .NET Properties tab to bring it to the front.
  3. In the Class Lifetime list, select the setting to be used for this service.
  4. If you select the Session setting, determine if the current Class Timeout value is correct.

    For more information, see The Class Timeout Value.

  5. On the File menu, click Save.

The Class Timeout Value

About this task

The Class Timeout value applies only to .NET services having a Class Lifetime setting of Session. The clock starts when the Package for Microsoft .NET creates an instance of the class. The clock is reset whenever a .NET service accesses the class. If time expires, the object is destroyed. The default value is three minutes. You must choose a different value if you know that the default timeout value would cause the object to be destroyed prematurely under normal usage.

To modify the Class Timeout value for a .NET service

Procedure

  1. In the Navigation panel, double-click the service for which you want to change the Class Timeout setting.
  2. Click the .NET Properties tab to bring it to the front.
  3. In the Class Lifetime list, make sure the Session setting is selected.
  4. In the Class Timeout field, type the correct timeout value, in minutes.
  5. On the File menu, click Save.

Invoking a .NET Service from Designer

To test a .NET service using Designer as the client, you use the Run command on the Run menu. Before you attempt to test .NET services, you should understand application domains and the forms of data marshalling available for .NET services. For information on application domains, see Application Domains.

Managing Application Domains

You can create and destroy application domains as explained below.

Using Services to Start and Destroy Application Domains

The first way is through the startDomain and destroyDomain services, which you can find in the WmDotNet package in the Navigation panel of Designer:

WmDotNet/wm/dotnet/Runtime

One advantage of using the startDomain service is that you can assign a .NET configuration file to modify the behavior of the application domain.

Using Integration Server Administratorto Destroy Application Domains

At the time you run a .NET service in Designer, you can specify an application domain in which to run it. If the application domain does not already exist, Integration Server creates it. This dynamic creation feature makes it easy to add application domains as you need them. For more information, see Running a .NET Service in Designer.

Note: If you do not specify an application domain, the service runs in the default webmDomain application domain.

Using Integration Server Administrator, you can destroy an application domain on the Manage Application Domain page. This method is easier than using the destroyDomain service because you can find the application domain within a table and click the Destroy link.

For more information, see The Manage Application Domains Page.

Marshalling Data

Marshalling is the process of packing one or more items of data into a message buffer prior to transmitting that message buffer over a communication channel.

If Integration Server were to call a .NET method and it returned an object, such as a SQL connection, Integration Server could not process the object because it has meaning only within .NET. There are two ways to marshall data across the division between Integration Server and .NET. The first way is to use a reference ID, or an instance ID. Instead of bringing the object over, Integration Server assigns an ID. If it is necessary to make another method call that uses that object as an input, Integration Server uses the reference ID. If you want to keep using the same object, such as SQL connection, you should use the reference ID. Note that the reference ID is valid only for the same application domain.

The other way to marshall data is by passing XML. .NET has a built-in XML serializer that takes that object, examines it, and turns it into an XML string. Integration Server can manipulate the XML string and modify data, and then use that XML string as input to another method. If you need to manipulate the object in Java in some way, use XML, but you should be aware of the possible drawbacks. The use of XML is inefficient because you are passing a large string instead of a single ID. Also you need to be careful in designing the manipulation of data within Integration Server because the .NET XML serializer may create an invalid object upon its return. For information on how to choose the marshalling type, see Running a .NET Service in Designer next in this chapter.

Running a .NET Service in Designer

About this task

To run a .NET service in Designer, do the following:

To run a .NET service in Designer

Procedure

  1. In the Navigation panel, double-click the .NET service you want run.
  2. Do one of the following:
    • In the Run menu, select Run As and click Run Service.
    • In the Designer toolbar, click the Run icon.
  3. If there is an Input field, type a value to test the service.
  4. In the domainName field, type the domain name of a new or existing application domain name on Integration Server.
    Note: If you do not specify an application domain, the service runs in the default webmDomain application domain.
  5. In the marshallingType list, select one of the following:
    Value Marshalling type
    refid Reference ID
    xml XML marshalling
  6. Click OK.

    Designer runs the .NET service on Integration Server and returns data as appropriate.