Wizards for Port Implementations

This section reviews the wizards used to specify the implementation options. The meaning of these options should now be much clearer.

There are four wizards used to bind an implementation to a port—one each for the technology used for binding. We cover each of these in turn here.

COM Component Binding Wizard

The COM Component Binding Wizard has six pages; some pages may not be shown, as described.

On the first page, you specify the port name. On the second page, Static or Dynamic Communication, you specify the instantiation options for the component (see Figure 10.10).

Figure 10.10 shows the three options of Static, Dynamic, and No Instantiation. The text provides a short description for each of these options. These concepts were discussed previously in the sections “Port References and Dynamic Ports,” “A Port Using COM Components,” and “Case 1: Application Calls a Method.”

On the third page, Class Information, you choose a registered COM component or specify that the class instance be acquired through a moniker implementation (see Figure 10.11).

Figure 10.11 shows the selection of the class with the name of Microsoft BizTalk Server Interchange 1.0 Type Library. The prog-id, BizTalk.Interchange.1, is not shown in Figure 10.11. If you select a moniker implementation to instantiate the class, then the class instance cannot be used with XLANG transactions.

On the fourth page, Interface Information, you choose the interface. If the class has only one interface, then this page does not appear. For components implemented using Visual Basic, class interfaces are shown with an underscore prefix.

On the fifth page, Method Information, you choose the methods that can be called through this port binding. The methods listed are those of the interface selected earlier. Figure 10.12 shows this page.

Figure 10.12 shows that two methods have been selected. You must select at least one. Buttons are provided to select all methods or to deselect all methods. This page is not shown if the interface has only one method.

On the final page, Advanced Port Properties, as shown in Figure 10.13, you specify options for Security, Transaction Support, State Management Support, and Error Handling.

For security options, if you specify that the sender's identity is Optional, then the schedule requests the identity but continues to run, even if it is not available. If you specify that the sender's identity is Required, then if the identity is not available, the message is ignored. In an incoming call, the caller gets the error E_ACCESSDENIED. For the background on security options, see the section “Security” earlier in the chapter.

For transaction support options, select the appropriate option based on the component and business process. The transaction concepts were covered previously in the section “Transaction Support.”

The state management options are chosen by selecting an item from the drop-down box. The choices are Holds No State, Holds State, But Doesn't Support Persistence, or Holds State, and Does Support Persistence. If you chose the last option, the component should implement the COM persistence interfaces. The state management concepts were covered previously in the section “State Management.”

For error handling there is only one option: Abort Transaction if the Method Returns a Failure HRESULT. You can set this option only if the port is used in a transaction context in the schedule. The associated transaction is aborted if HRESULT denotes a failure. This option is useful for COM components not configured in COM+ or which do not natively support transactions. It works with all types of XLANG transactions.

We next look at the Script Component Binding Wizard.

Script Component Binding Wizard

The Script Component Binding Wizard is similar to the COM Component Binding Wizard, and it has six pages.

The first page is used to name the port. The second page specifies the instantiation options, as shown in Figure 10.10.

Instantiation concepts were covered previously in the sections “Port References and Dynamic Ports,” “A Port Using COM Components,” and “Case 1: Application Calls a Method.”

On the third page, Specify the Script File, you can enter or browse to the path of the Windows Scripting Component file, with the .wsc extension.

On the fourth page, Component Instantiation Information, you specify whether the schedule should use a script file moniker or a prog-id to construct the component instance. Figure 10.14 shows this page.

This page is akin to the class information for a COM component. This page is not shown if the schedule does not have to construct the component instance—that is, when you select either Dynamic or No Instantiation on the second page.

On the fifth page, Method Information, you select the method to use with this port binding. This page is similar to Figure 10.12 and is skipped if the script component has just one method.

The final page, Advanced Port Properties, is similar to Figure 10.13. One difference is that you cannot specify the state management options for scripting components—they cannot persist state.

Message Queuing Binding Wizard

This section covers the wizard for the MSMQ messaging technology. The Message Queuing Binding Wizard has four pages. Figure 10.15 shows the first page.

On this first page, you can either create a new port and provide a name for it, or, if you have created unbound ports earlier (see the previous section “Ports”), then you can choose to use them with MSMQ.

The second page, Static or Dynamic Queue Information, is shown in Figure 10.16.

On this page, you choose to use a preexisting queue or a queue known only at runtime. If you choose the dynamic queue option, then you must identify how the schedule will get a reference to such a queue (at runtime) by connecting a link from a message field to the Port References message on the Data page. See the sections “Ports,” “Port References and Dynamic Ports,” “A Port Using Message Queuing,” and “Defining Data Flow Through Messages” for more information.

The third page, Queue Information, is shown in Figure 10.17.

On this page, you specify the queue you want to use. You have two options: create a new, uniquely named, queue for each instance of the schedule or create a known queue shared among all instances of the schedule. If a new queue is created for every schedule instance, the queue itself is uniquely named and created by the XLANG Scheduler Engine. The naming algorithm consists of appending a GUID to the name prefix you specify. Such a queue provides a useful port reference for getting back response document(s) to a specific schedule instance. The port reference can be used to resolve a dynamic port in another schedule later. In Figure 10.3, you could regard schedules A and B to be just two instances of the same schedule, and the dynamic port in schedule C can be resolved to the correct queue. If, instead, a known queue is used, then the queue must be created before the schedule instance is launched. If such a queue is used to resolve a dynamic port, then all responses will end up in the same queue.

The fourth, and the final, page is Advanced Port Properties, shown in Figure 10.18.

On this page, you have two sets of options to select: Security and Transaction Support.

Under the Security options, if you specify that the sender's identity is Not Required, then the __Sender__ field for the received message is always blank. If you specify that the sender's identity is Optional, then the authenticated identity of the sender (if available) is provided in the __Sender__ field. The value is the same as in the MSMQ message's SenderID property. If you specify that the sender's identity is Required, then the schedule receives the message only if the sender's authenticated identity is available.

Otherwise, the message is relegated to a dead letter queue, named after the COM+ application hosting the schedule, and an event is posted to the application event log. See also the previous section, “Security.”

Under the Security options, you can also specify the Windows Group or User Name that should be used to post messages to the queue. These options are available only for a static queue.

In the Transaction Support area, you select whether Transactions Are Required with This Queue. If the queue is in fact not transactional, then, at runtime, the XLANG scheduler will fail-fast the schedule instance (that is, promptly destroy the instance).

BizTalk Messaging Binding Wizard

The BizTalk Messaging Binding Wizard has a different sequence of pages depending on whether messages are sent or received. The page sequence is shown in Figure 10.19. There are in all five pages; however, the actual pages shown depend on the choices made. These pages are described next.

On the first page, you specify the name of a new port or use an existing unbound port (see the section “Ports” earlier in the chapter). This page is shown in Figure 10.20.

On the next page, Communication Direction, you can choose to either send or receive messages. This page is shown in Figure 10.21.

As shown in Figure 10.19, the wizard pages shown next depend on whether you choose to send or receive documents. If you select to send messages, then the Static or Dynamic Channel Information page appears (see Figure 10.22). On this page, you can specify the name of a preexisting channel or a dynamic channel.

If you select Dynamic Channel, then the channel to deliver the message is determined at runtime. BizTalk Messaging Services already defines an algorithm for channel selection. Recall from Chapter 6 that this algorithm is a channel that is selected based on the triplet consisting of the source address, the destination address, and the document type.

The candidate channel must be configured with the XLANG schedule as its source and must be associated with an open messaging port. The destination address is specified at runtime. On the Data page, you choose a field in a received message and link it to the port reference for the dynamic channel. The field should contain a destination address for the open messaging port. The last leg of the triplet is the document type. You specify this when you use the XML Communication Wizard—the message flowing through the dynamic channel uses this document type.

There should be exactly one channel configured to meet the previous selection criteria. If this is not so, then the schedule instance will fail-fast and generate an application event-log entry. For additional discussion of dynamic channels, see the section “A Port Using BizTalk Messaging” earlier in the chapter.

This sequence of pages concludes the set of pages associated with the Send option. If you choose the Receive option instead, then the XLANG Schedule Activation Information page is displayed next, shown in Figure 10.23. See the sequence of pages in Figure 10.19.

On this page, you select whether the received message results in the activation of a new schedule instance. If you choose Yes, then there are restrictions on how this port can be used. These restrictions are

• Only one port in the schedule can be configured to activate the schedule.

• Only one message can be received. You cannot use this port to repetitively get multiple messages in a loop or use it in multiple actions to receive messages.

• You cannot forward a reference to this port via any message on the Data page. In other words, you cannot use this to resolve a dynamic port reference elsewhere.

There are no more steps to complete in the wizard at this point.

On the other hand, if you choose No—that is, the incoming message does not activate a new schedule—then you are presented with the page shown in Figure 10.24, Channel Information. Note the wizard page sequence shown in Figure 10.19 again to see what stage of the wizard you are at.

On this page, you specify the channel that receives the incoming document over HTTP and the HTTP address where BizTalk Messaging Service receives the document. Recall from the section “A Port Using BizTalk Messaging,” and also depicted in Figure 10.6, that HTTP is the only supported protocol to receive documents from a dynamic channel.

A sample ASP page, called ReceiveResponse.asp, is provided with the product for receiving documents over HTTP. This ASP page must be installed in an appropriately secured Web site. The sending dynamic channel constructs a URL of the following form to deliver the message:

https://MyMachine/ReceiveResponse.asp?channel=ChMyChannel&qpath= MyMachine.MyDomain.com
private$ChMyChannel{53E259E9-938C-4629-9E05-6472A5CFE16D} 

Note, in Figure 10.24, that the ReceiveResponse.asp page is accessed in the URL. The arguments in the URL specify the channel and the queue set up by the source XLANG schedule to receive the document.

The argument channel contains the name of the channel to receive the response document. You must create this channel. If this channel is not present, you get an application event log entry (from the XLANG Scheduler, with event category of WFBinding) stating that a valid open destination channel could not be found. This receiving channel can be used to validate and transform the incoming response document.

The argument qpath is treated as the destination identifier for document routing. Note that it is a per-schedule instance of an MSMQ queue, with the name constructed from the channel name and a GUID. This queue is created by the sending XLANG schedule as an endpoint to receive the response document. This queue is the target of the open destination port attached to the channel.

The system receiving the original document and generating the response does not have to run BizTalk Server. It merely posts the response, however generated, to the URL it receives embedded in the original document.

The server-side script ReceiveResponse.asp extracts the channel name and queue path information in the URL and uses this information to submit the document to BizTalk. The extracted channel and queue path are provided as routing information to BizTalk.