BizTalk 2006 : Creating More Complex Pipeline Components (part 3) - Validating and Storing Properties in the Designer

As in any component development model, it is necessary to store properties that a user selects for your component so you can load them at runtime and also validate that the values chosen by the user are appropriate. To perform validation, you need to use the IComponentUI interface and implement the Validate function. To store and load information for runtime use, you use the IPersistPropertyBag interface and implement the Load and Save functions. Example method implementations are given in the following text.

Validating User Input

IComponentUI.Validate is used to validate any property information and display an error message to the user when the project is compiled. Most implementations use either a collection or an ArrayList to store the errors. You then need to return the IEnumerator object from the ArrayList or collection at the end of the method with all the error messages you want displayed populated.

The following example demonstrates how you can validate a developer's input from within the IDE. Any errors are returned to the user as errors in the IDE's error window.

'<summary>
'The Validate method is called by the BizTalk Editor during the build
'of a BizTalk project.
'</summary>
'<param name="obj">An Object containing the configuration 'properties.</param>
'<returns>The IEnumerator enables the caller to enumerate through a collection of
'strings containing error messages. These error messages appear as compiler error
'messages. To report successful property validation, the method should return an
'empty enumerator.</returns>
Public Function Validate(ByVal obj As Object) As System.Collections.IEnumerator_
Implements Microsoft.BizTalk.Component.Interop.IComponentUI.Validate
'example implementation:
Dim errorArray As New ArrayList
errorArray.Add("This is an error that will be shown...")
return errorArray.GetEnumerator
End Function

					  

Using the Property Bag to Store Property Information

In order to store property information for pipeline components, you need to implement the IPersistPropertyBag interface and give an implementation to the Save and Load methods. These methods pass in the representative IPropertyBag object that will be used to store the property information. The IPropertyBag is simply a structure that will hold a set of key/value pairs. The key is a string, and the value is of type Object so it can accept any type. You may ask yourself, "Why not store the object itself rather than storing the name of the schema and constructing a New() object in the Load method?" The answer is because the Save function of the component will fail if you do this. When the properties are written to the ContextPropertyBag, they are actually expressed within the BTP file as XML so that they can be used for perinstance pipeline configuration.

'<summary<
'Loads configuration properties for the component
'</summary>
'<param name="pb">Configuration property bag</param>
'<param name="errlog">Error status</param>
Public Overridable Sub Load(ByVal pb As _
Microsoft.BizTalk.Component.Interop.IPropertyBag, ByVal errlog As Integer) _
Implements Microsoft.BizTalk.Component.Interop.IPersistPropertyBag.Load


Dim val As Object = Nothing
val = Me.ReadPropertyBag(pb, "MyDocSpec")
If (Not (val) Is Nothing) Then
        Me._MyDocSpec = New _
Microsoft.BizTalk.Component.Utilities.SchemaWithNone(CType(val, String))
End If
val = Me.ReadPropertyBag(pb, "OutboundDocumentSpecification")
If (Not (val) Is Nothing) Then
        Me._OutboundDocumentSpecification = New _
Microsoft.BizTalk.Component.Utilities.SchemaWithNone(CType(val, String))
End If
val = Me.ReadPropertyBag(pb, "FileRootNode")
If (Not (val) Is Nothing) Then
        Me._FileRootNode = val
End If
val = Me.ReadPropertyBag(pb, "DataElementNode")
If (Not (val) Is Nothing) Then
        Me._DataElementNode = val
End If
End Sub

'<summary>
'Saves the current component configuration into the property bag
'<summary>
'<param name="pb">Configuration property bag</param>
'<param name="fClearDirty">not used</param>
'<param name="fSaveAllProperties">not used</param>
Public Overridable Sub Save(ByVal pb As _
Microsoft.BizTalk.Component.Interop.IPropertyBag, ByVal fClearDirty As Boolean, _
ByVal fSaveAllProperties As Boolean) Implements _
Microsoft.BizTalk.Component.Interop.IPersistPropertyBag.Save

Me.WritePropertyBag(pb, "MyDocSpec", Me.MyDocSpec.SchemaName)
Me.WritePropertyBag(pb, "OutDocSpec", Me.OutboundDocumentSpecification.SchemaName
Me.WritePropertyBag(pb, "FileRootNode", Me.FileRootNode)

					  

Me.WritePropertyBag(pb, "DataElementNode", Me.DataElementNode)
End Sub

'<summary>
'Reads property value from property bag
'</summary>
'<param name="pb">Property bag</param>
'<param name="propName">Name of property</param>
'<returns>Value of the property</returns>
Private Function ReadPropertyBag(ByVal pb As _
Microsoft.BizTalk.Component.Interop.IPropertyBag, ByVal propName As String) As _
Object

Dim val As Object = NothingTry
      pb.Read(propName, val, 0)
      Catch e As System.ArgumentException
Return val
      Catch e As System.Exception
      Throw New System.ApplicationException(e.Message)
End Try
Return val
End Function

'<summary>
'Writes property values into a property bag.
'</summary>
'<param name="pb">Property bag.</param>
'<param name="propName">Name of property.</param>
'<param name="val">Value of property.</param>
 Private Sub WritePropertyBag(ByVal pb As _
Microsoft.BizTalk.Component.Interop.IPropertyBag, ByVal propName As String, ByVal _

val As Object)Try
      pb.Write(propName, val)
      Catch e As System.Exception
      Throw New System.ApplicationException(e.Message)
End Try
End Sub

					  

Custom Properties and Per-Instance Pipeline Configuration

Per-instance pipeline configuration allows you to change the values of custom properties using the BizTalk Administration Tools. The user interface provides you with a mechanism to set the values for pipeline properties dynamically for a receive location without having to create a new custom pipeline for every new receive location. A few points of interest when attempting to use this feature with a custom pipeline and pipeline components are described here.

Custom pipeline component properties for per-instance pipeline configuration are actually stored within the .btp file for the pipeline definition. A sample of the file follows. If you find that your custom properties are not appearing in the per-instance pipeline configuration document, you can manually add them to the XML of the .btp file and they will appear.

<?xml version="1.0" encoding="utf-16"?>
<Document xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
PolicyFilePath="BTSReceivePolicy.xml" MajorVersion="1" MinorVersion="0">

  <Description />
  <Stages>
    <Stage CategoryId="9d0e4103-4cce-4536-83fa-4a5040674ad6">
      <Components />
    </Stage>
    <Stage CategoryId="9d0e4105-4cce-4536-83fa-4a5040674ad6">
      <Components />
    </Stage>
    <Stage CategoryId="9d0e410d-4cce-4536-83fa-4a5040674ad6">
      <Components>
        <Component>
          <Name>ABC.BizTalk.PipelineComponents.Decoder</Name>
          <Properties>
            <Property Name="MyUnTypedProperty" />
            <Property Name="MyStringProperty">
              <Value xsi:type="xsd:string">My String Value</Value>
            </Property>
          </Properties>
          <CachedDisplayName>Decoding Component</CachedDisplayName>
          <CachedIsManaged>true</CachedIsManaged>
        </Component>
      </Components>
    </Stage>
    <Stage CategoryId="9d0e410e-4cce-4536-83fa-4a5040674ad6">
      <Components />
    </Stage>
  </Stages>
</Document>

					  

• In the .btp file for the pipeline definition, you can set the default data of the pipeline component property by inserting a value in the property's <Value> element.

• The <Value< that you insert must be an XSD type. For example, the type must be xsd:string for a string value, or xsd:int for an integer value.