Pro BizTalk 2006 phần 3 potx

• Performance: Large message properties cannot be “streamed” and must be entirely loaded into memory by the runtime. This will become an issue if you write large values for message properties into the message context. • Overwriting of promoted properties: If you have promoted a property to the message c ontext, and you issue a context write operation, the property is no longer promoted. • Dealing with Nulls: Null properties are not persisted to the context. If you set a prop- erty’s value to Null, it will no longer exist, and you cannot see a context property in the HAT with a value of Null. Distinguished Fields There are two types of property promotion: distinguished fields and property fields. The latter type uses property schemas. In the BizTalk schema editor, you manage both of these types of property promotion by using the Promote Properties dialog box, which you access by using the Promote Properties property of the Schema node. Distinguished fields are only useful when they are accessed within orchestration. Promoted properties can be accessed either in orches- trations or from custom code, routing, and pipelines. Distinguished fields, on the other hand, cannot be used for routing and are only used by the orchestration engine. When dealing with large messages, this can save significant server processing, as the engine would need to use XPath expressions to search through the docu- ment to find the piece of data that it needs each time the expression is evaluated. This way, the data is loaded once when the document is parsed by the runtime engine. Distinguished fields are used within orchestrations to move required elements into the context and only read the context property within the orchestration without having to load the entire document into memory. Distinguished fields also offer nice IntelliSense capabilities within the orchestration expression editor and message assignment shapes. Depending on the type of access that is needed, you can choose to create either promoted properties or distinguished fields depending on how the property will be used. Distinguished fields do not require the creation of a corresponding property schema. Using Port Filters and Content-Based Routing As stated in the pr evious section, subscriptions and context properties are integral to the mes- saging subsystem. Property schemas are the mechanism by which the context properties are stored in the message context. When creating schemas, you can define a property schema that will hold any custom pr operties that will be used for r outing the inbound message. To create a custom property schema, you need to create a schema and a property schema to hold the properties. In order to move a value from the data of the message into the context, it is neces- sar y to “ promote” the property into the context property bag. The BizTalk Message Bus auto- matically promotes system-level properties from the system property namespaces, depending on the type of inbound and outbound transports that are being used. Each adapter will require and hence pr omote v alues that it needs to send and r eceive the message according to its par- ticular protocol. In the schema definition of the message, property promotion is done by first associating the pr oper ty schema to the message and choosing the pr operty to promote. Most architects CHAPTER 3 ■ THINKING INSIDE THE BOX 79 6994ch03final.qxd 10/2/06 12:35 AM Page 79 don’t understand how messages are routed within the product or how to use the property schemas to affect the subscription. Exercise 3-1 will show you how you can use the property promotion to implement routing logic. Exercise 3-1: Using Custom Promoted Properties to Route Messages Let’s continue our example from Chapter 2 of an organization that takes inbound documents from multiple sources, normalizes them to a canonical input schema, and sends them to different outbound locations. Assume that there are three systems: a web site, a POS application, and an automated FTP upload location. Each of these locations takes a different schema and must map it to internal schema. This mapped message then needs to be sent to the ERP system. However, as an added piece of functionality, documents from the web site need to be sent to a sepa- rate location as well, and documents from the POS system need to be sent to a file system directory so they can be batch uploaded at a later time. Figures 3-3 and 3-4 define the schema for the internal messages and a possible solution architecture. CHAPTER 3 ■ THINKING INSIDE THE BOX80 Figure 3-3. I nternal order request schema 6994ch03final.qxd 10/2/06 12:35 AM Page 80 The requirements for this solution are quite common in most BizTalk projects, and most new BizTalk architects design it incorrectly. Generally those unfamiliar with the subscription nature of the Message Bus will tend to build an orchestration that has logical ports directly bound to the physical ports. The orchestration would then use Decide shapes to send the message to the appropriate send port, which will then send the message on its way. An even worse solution is to create three orchestrations, each of which receives the inbound message directly from the receive location, executes the map from within the orchestration, and then has a static bound port that is bound to the send port from within the orchestration. This problem requires only messaging to be solved. No orchestra tions should be created here since no business logic is needed. Routing the message to the correct location is not business logic, and as such, an orchestration is not the correct tool to use from the BizTalk Server toolbox. T o implement the routing logic, subscriptions need to be crea ted that allow the inbound message, once it has been ma pped, to be sent to the correct port. Here, you crea te filters based on the MessageType context property tha t allow the Messaging Engine to automatically forward any messages of type http://ABC.FulFillment. BizTalk.Schemas.OrderSchema#Order to the ERP system. The filter of the port will modify the subscription in the Messa gebox accordingly. In the filter properties of the ERPSendPort, the expression sho wn in Figure 3-5 will be present. CHAPTER 3 ■ THINKING INSIDE THE BOX 81 Figure 3-4. Solution architecture 6994ch03final.qxd 10/2/06 12:35 AM Page 81 You still have not seen how to solve the problem of differentiating messages that are received from each of the three separate order producing systems. Notice that the internal schema definition includes an element that will allow you to store that data should it be available, but there are two problems: a) how do you get the value in this element, and b) how can you route messages based on it. For adding this value into the data document, you use the inbound map defined on the receive port. All you need to do is create a map from the external schema to the internal schema and assign a constant value for the SourceSystem element. To allow you to route on the SourceSystem property, you need to create a property schema to define what prop- erties you want to store in the context and to allow the Messaging Engine to promote the value from the data in your inbound document. To do this, add a new item to the schema project: in the list of BizTalk project items, choose Property Schema. Add an attribute to the schema called SourceSystem. This can be seen in Figure 3-6. Figure 3-7 shows the schema for the internal order property schema as viewed in the BizTalk schema editor. CHAPTER 3 ■ THINKING INSIDE THE BOX82 Figure 3-5. ERPSendPort properties 6994ch03final.qxd 10/2/06 12:35 AM Page 82 CHAPTER 3 ■ THINKING INSIDE THE BOX 83 Figure 3-6. Web site to internal schema map Figure 3-7. Order property schema 6994ch03final.qxd 10/2/06 12:35 AM Page 83 The next step is to associate the custom property schema to the internal order schema. To do this, right-click the SourceSystem element in the internal order property schema and choose Promotions ➤ Show Promotions. This i s demonstrated in Figure 3-8. Next, click the Promoted Properties tab and click the open folder icon. Once you have chosen OrderPropertySchema, highlight the SourceSystem element on the left and click the Add associate button. This will add the element to the list of promoted properties. Notice that since there is only one property defined in the property schema, the editor automatically associates this field with the SourceSystem property in the property schema. This can be seen in Figure 3-9. Compile the project and deplo y it to the Management Database. Once the schema’s assembly is deployed to the Management Database, it will automatically be available in the list of properties in a ports filter. If you create a new send port and want to only send documents from the web site, you can add it as a filter, and this will automatically update the subscription as shown in Figure 3-10. Another important fact to note is that in this situation, you only need to create one receive port with three receive locations. You also need to create three maps and add them each to the transforms on the port. The pipeline will examine the inbound schema for each map and send the inbound document to the correct map. If no port has a subscription for a matching inbound message type, an error will occur, and the message will become suspended. CHAPTER 3 ■ THINKING INSIDE THE BOX84 Figure 3-8. Property Schema Type Picker 6994ch03final.qxd 10/2/06 12:35 AM Page 84 CHAPTER 3 ■ THINKING INSIDE THE BOX 85 Figure 3-9. Manually promoting the SourceSystem property Figure 3-10. Routing based on a custom promoted property 6994ch03final.qxd 10/2/06 12:35 AM Page 85 Using System Property Schemas As mentioned previously, a number of system property schemas come with the product. Most of these property schemas exist to support each of the transports and adapters included with t he product out of the box. Most of the time, each new transport or application adapter will bring with it a new property schema that is used to define any custom metadata needed to process the message by the adapter. Each of the system property schemas is included in the base assembly Microsoft.BizTalk.GlobalPropertySchemas.dll. Referencing this assembly from a BizTalk project in Visual Studio will allow you to access each of the schemas as you would with any other schema type. Modifying Values from System Property Schemas: Simple Example So at this point many people ask the question, “Big deal, I can modify values that BizTalk uses, so why would I need this ability?” In order to fully understand why the creation of property schemas becomes an invaluable tool, let’s look at a simple example. Continuing with the sce- nario from Exercise 3-1, let’s assume that an order received from the bulk order system needs to be written to a file location on a server within the organization. Let’s also assume that we need to dynamically modify the name of this file depending on some value from the message: the customer ID plus the character “#” and the total amount of the order. At first, modifying the file name based on a message value seems like an easy thing to do, but it becomes a little more complicated when you look at it. In reality, there are three solu- tions to the problem. Solution A would be to use an orchestration with a dynamic port and within the orchestration use some XPath expressions to get the data you need from the mes- sage; dynamically set the address of the file adapter; and send the file to the dynamic port. However, in reality there is a cost to doing this. First, you are breaking one of the cardinal rules of BizTalk—you are using orchestrations to do routing logic. Second, you have an orchestra- tion that is exclusively bound to a port and has to be deployed, enlisted, and started with the port it is bound to. 3 Third, if this were a large message, using XPath will force the orchestration engine to load the entire document into memory in order to parse out the values from the XPath expression. 4 Solution B is to use the BizTalk Messaging Engine and have it do the work for you. To implement this solution, you use the macro functionality to write the message in the send port. You need to modify your internal order schema so that there is a new element called OutBoundName or something similar , and y ou need somewhere to promote this property to. For this, use the file adapter property schema. In the internal order schema, there is an ele- ment called ReceivedFileName. What you do is modify the BulkOrderToInternal.btm map so that the value of the CustomerID along with the total is concatenated into your new element in the internal schema. You still have to promote the CustomerID property into the context. CHAPTER 3 ■ THINKING INSIDE THE BOX86 3. In later chapters, we will discuss orchestrations with direct-bound ports (i.e., not bound to a physical por t, but bound to the M essagebo x database) vs . or chestrations with static/dynamic bindings. There ar e pr os and cons to each, but there are more pros than cons to a direct port, and generally they are preferable to static or dynamically bound ports. 4. We could use distinguished properties to get around this. The orchestration engine will not load the entire document if the property were distinguished. As stated previously, these would be written into the context when the message is processed by the Messaging Engine. However, the point is that using XP ath in or chestr ations is costly , especially on lar ge messages. 6994ch03final.qxd 10/2/06 12:35 AM Page 86 To do that, in the Property Promotions tab of the schema, add a reference to the file adapter’s property schema. The next step is to create a send port that subscribes to the correct message type, set the outbound destination in the send port to the desired directory, and set the file name to be %sourcefilename%. The BizTalk Messaging Engine will use whatever value is stored in the ReceivedFileName message context property when writing this value out. Since you have changed it and promoted it, the engine will use your new value instead of the original one as shown in Figure 3-11. Solution C is to create a custom pipeline component, add it to a stage in a custom receive pipeline, and have it promote the value you want into the context using the message API. The code would look something like the following: Private Sub PromoteProperties(ByVal message As IBaseMessage, ByVal CustomerID As _ String, ByVal OrderTotal As Decimal) Dim BTSFilePropertiesNamespace As String = _ "http://schemas.microsoft.com/BizTalk/2003/file-properties" Dim FileName As String 'Get the original directory the file was received from by reading the message _ context and creating a FileInfo object Dim FileInfoObject As new System.IO.FileInfo(message.Context.Read("ReceivedFileName", _ BTSFileropertiesNamespace)) CHAPTER 3 ■ THINKING INSIDE THE BOX 87 Figure 3-11. Promoting a value using a system property namespace 6994ch03final.qxd 10/2/06 12:35 AM Page 87 ' Replace the original name with the new one FileName = FileInfoObject.DirectoryName + "\\ + CustomerID + "#" + _ OrderTotal.ToString() + ".xml" m essage.Context.Promote("ReceivedFileName", BTSFileropertiesNamespace, FileName) End Sub The send port is configured the same as in solution B. Although solution C uses the Mes- saging Engine to accomplish the task, it requires you to write a custom pipeline and pipeline component that you would then have to maintain. The benefit of solution C is that it does not require you to modify the internal schema or transformation in any way. Solution C would be ideal if you had a production-emergency type of scenario where you needed to implement the proposed change with as little possible downtime or modification to the deployed solution. All you would need to do is deploy the pipeline assembly to each of the BizTalk servers, along with copying the pipeline component to the %Program Files\Microsoft BizTalk Server 2006\ Pipeline Components\ directory and changing the pipeline configuration on the receive port. In this scenario, there would be no server downtime and few configuration changes required. The trade-off is that you would have additional custom logic and custom assemblies that must be maintained and deployed with the solution as a whole. Modifying Values from System Property Schemas: Extended Example Now that you see a simplistic usage of modifying a system property, we will show you some- thing a little more interesting. Continuing with the previous example, assume that you need to send information to your ERP system with messages received from the web site. Also assume that there have been performance problems calling the ERP solution. Currently the ERP system uses a custom API written in VB 6.0 and exposed through COM+ objects. You need to track how long these calls are taking, but you want the information included within the Messagebox and you want it bundled with all the other tracking information that is stored in the database and accessible through HAT for the server administrators. You also want individual tracking information per message so that you can correlate what types of transactions are taking the most time. Assume that the code to call the API is fixed and cannot be modified. Due to architectural limitations, you also cannot impose a wrapper (i.e., web service or custom adapter), you must call the API dir ectly as you would be nor mally, and these calls must be synchronous because the API will not support asynchronous calls due to threading issues. Currently, the API is called from an Expression shape inside an orchestration, and depending on a series of return v alues, different business logic is executed. As an added bonus, the administrators want a copy of all messages that take more than 5 seconds to process to be sent to a drop location where those messages can be viewed offline. The development team does not want any major logic modifications to the existing r eceive ports/send ports/orchestrations to implement the logging logic (i.e., you can’t store the tracking value somewhere and have the orchestration insert a Decide shape that sends a copy to the send port). Also, message tracking is not enabled, since this is a production system, and the administrators do not want to decrease the per- formance of the system any further. CHAPTER 3 ■ THINKING INSIDE THE BOX88 6994ch03final.qxd 10/2/06 12:35 AM Page 88 [...]... information written to the subscription 93 6994ch03final.qxd 94 10/2/06 12 :35 AM Page 94 CHAPTER 3 s THINKING INSIDE THE BOX Figure 3- 15 Receive port configuration Figure 3- 16 Orchestration Receive shape filter 6994ch03final.qxd 10/2/06 12 :35 AM Page 95 CHAPTER 3 s THINKING INSIDE THE BOX The BizTalk Management Database Up until this point, our discussions regarding BizTalk schemas, deployment, and namespaces... dynamically to some endpoint In BizTalk Server 2006, getting at suspended messages is a simple problem to resolve The BizTalk product team added a set of context properties that are available to be subscribed on and routed to Error handling context properties are defined within the http://schemas microsoft.com /BizTalk/ 2005/error-report property schema The new context properties are as follows: • Description... tell the engine that data for your property will not come from the message and that you will provide it To fix this, you need to set the Property Schema Base for the property under the Reference section of the schema editor as shown in Figure 3- 14 6994ch03final.qxd 10/2/06 12 :35 AM Page 91 CHAPTER 3 s THINKING INSIDE THE BOX Figure 3- 14 Changing the base type for a property To the runtime, this determines... managing, and supporting BizTalk using the ExplorerOM API, see Chapter 10 95 6994ch03final.qxd 96 10/2/06 12 :35 AM Page 96 CHAPTER 3 s THINKING INSIDE THE BOX Choose Add a New Project Item, then choose schema file Name it TestSchema Switch to the Properties window, select the root node, and change the Node Name property to ExplorerWMI as shown in Figure 3- 17 Figure 3- 17 ExplorerWMI project within Visual... Figure 3- 18 Switch to the Orchestrations project, add an orchestration, and configure it to pass through any received messages to a file-based send port as shown in Figure 3- 19 8 http://dotnet.jku.at/applications/course 03/ Reiterer/ 6994ch03final.qxd 10/2/06 12 :35 AM Page 97 CHAPTER 3 s THINKING INSIDE THE BOX Figure 3- 18 .NET Assembly Viewer Figure 3- 19 Simple pass-through orchestration 97 6994ch03final.qxd... together by a promoted property called the InterchangeID In BizTalk 2004, calling a pipeline from an orchestration was not a supported scenario In BizTalk 2006 this has been greatly improved Unless the application needs to aggregate messages inside the orchestration, there is no real reason to do this Message aggregation is the primary reason why this feature was improved in BizTalk 2006 Many new BizTalk. .. will not be inside the message • PartContextPropertyBase: This tells the runtime that the value for the property will be a part of the MessagePart context The key takeaway is that if you are promoting properties that do not exist in the message, be sure to set the proper base type for the property (i.e., MessageContextPropertyBase) As you can see, using system properties can solve a number of rather complex... store it in the property MessageTracking.AdapterTransmitEndTime since that property is of type System.DateTime There is another property called MessageTracking.ActivityIdentity that is of type string, which will allow you to store anything you want You simply store your computed time in that property and use it to route your messages as shown in Figure 3- 13 89 6994ch03final.qxd 90 10/2/06 12 :35 AM Page... in Figure 3- 20 against the bt_DocumentSpec table and check out your results As you can see in Figure 3- 23, the document specification is deployed twice, pointing to different assemblies: one pointing to the assembly created when you deployed XSD schemas, and another to the assembly containing classes produced by the XSD.EXE tool Figure 3- 23 Multiple assemblies, same namespace 101 6994ch03final.qxd... in catalog.Schemas) { Console.WriteLine("\t{0}#{1}", schema.TargetNameSpace,schema.RootName); } } } } 1 03 6994ch03final.qxd 10/2/06 12 :35 AM Page 104 6994ch04final.qxd 10/2/06 12 :32 AM CHAPTER Page 105 4 sss Pipelining and Components P ipelines are probably the least properly utilized tools in the BizTalk toolbox Pipelines are designed to do one thing well: Examine and potentially modify messages or . order property schema as viewed in the BizTalk schema editor. CHAPTER 3 ■ THINKING INSIDE THE BOX82 Figure 3- 5. ERPSendPort properties 6994ch03final.qxd 10/2/06 12 :35 AM Page 82 CHAPTER 3 ■ THINKING. INSIDE THE BOX 83 Figure 3- 6. Web site to internal schema map Figure 3- 7. Order property schema 6994ch03final.qxd 10/2/06 12 :35 AM Page 83 The next step is to associate the custom property schema. suspended. CHAPTER 3 ■ THINKING INSIDE THE BOX84 Figure 3- 8. Property Schema Type Picker 6994ch03final.qxd 10/2/06 12 :35 AM Page 84 CHAPTER 3 ■ THINKING INSIDE THE BOX 85 Figure 3- 9. Manually promoting