Defining design-time properties using basic .NET data types

Published on : Jan 31, 2007

Category : BizTalk Server



Recently I was building a pipeline component which requires a simple design time property. Even though I've written a white paper about it Understanding Design-Time Properties for Custom Pipeline Components in BizTalk Server I couldn't remeber all the syntax on top of my head. So, I opened the document for a quick view. I just copied a section from the article which explains the basic steps and published it here. View the full article for detailed explanation of some of the advanced concepts.

Let’s start with an example where you need three properties—ConnectionString (string), SaveContext (bool), and LogLevel (enum). To define these properties, you need to perform the following steps within your pipeline component:

Step 1: Define the enumeration type required.

public enum LogLevelType






Step 2: Define private field variables.

private string _connectionString = string.Empty;

private bool _saveContext = false;

private LogLevelType _logLevel = LogLevelType.Information;

Step 3: Define public design-time properties.

public string ConnectionString


get{return _connectionString;}

set{_connectionString = value;}


public bool SaveContext


get{return _saveContext;}

set{_saveContext = value;}


public LogLevelType LogLevel


get{return _ logLevel;}

set{ _logLevel = value;}


Step 4: Implement the Load method of the IPersistPropertyBag interface.

public virtual void Load(Microsoft.BizTalk.Component.Interop.IPropertyBag pb, int errlog)


            object val = ReadPropertyBag(pb,"ConnectionString");

            if (val != null) _connectionString = (string)val;

            val = ReadPropertyBag(pb, "SaveContext");

            if (val != null) _saveContext = (bool)val;

            val = ReadPropertyBag(pb, "LogLevel");

            if (val != null) _logLevel = (LogLevelType)val;


The helper function ReadPropertyBag is used to read the design-time properties from the property bag.  Error-handling code inside this function is required when the component is loaded inside the pipeline designer for the first time. At that point there are no values associated with the properties, which results in an exception. This helper function catches and suppresses the exception.

Private object ReadPropertyBag(Microsoft.BizTalk.Component.Interop.IPropertyBag pb, string propName)


            object val = null;



                pb.Read(propName, out val, 0);


            catch (System.ArgumentException )


                return val;


            catch (System.Exception e)


                throw new System.ApplicationException(e.Message);


            return val;


Step 5: Implement the Save method of the IPersistPropertyBag interface.

public virtual void Save(Microsoft.BizTalk.Component.Interop.IPropertyBag pb, bool fClearDirty, bool fSaveAllProperties)


            object val = _connectionString;

            pb.Write("ConnectionString", ref val);

            val = _saveContext;

            pb.Write("SaveContext", ref val);

            val = (LogLevelType)_logLevel;

            pb.Write("LogLevel", ref val);


Step 6: Implement the GetClassID and InitNew methods of the IPersistPropertyBag interface.

   Public void GetClassID(out System.Guid classid)


            classid = new System.Guid("AC21E483-C9BF-41F1-9AF0-2031528535C6");


The GetClassID method needs to return a unique identifier that represents the component within unmanaged code, which will allow interoperability with unmanaged code.

Note: The BizTalk 2004/2006 messaging engine is built using unmanaged code.

public void InitNew(){}

For basic data types you can leave the InitNew implementation blank, since we don’t have any structure, data, cache, or object to initialize for our sample.  

After you compile the component and insert it into a BizTalk pipeline (see “Using the custom pipeline component within a BizTalk pipeline” later in this article), the properties will be displayed in the property grid as shown in the following figure.