BizTalk Samples

I am looking for input on the practicality of using the BizTalk Adapter Framework to build a custom adapter.

  • For those of you who have used it what were your experiences, good or bad?
  • Can you describe the development process as to how you took the Framework and turned it into your adapter?
  • What documentation did you use?
  • Does Microsoft provide adequate documentation on the process?
  • Would a step-by-step 'how to' document cut down on development time and be useful?

Comments (15)
  1. Steve says:

    We built an adapter that’s been in prodcution for some time that combines the Data Access Application Block and the Adapter SDK. The result is a cross database polling and sending adapter. The learning curve on the adapter SDK was a little steep but once I was past that, it wasn’t bad. I used the documentation and samples that ship with the adapter SDK in BizTalk 2005. To be honest, the documentation was a little sparse. Yes, a step by step document would be quite useful. Also, one issue I ran into with the SDK concerned StandardReceiveBatchHandler. Do not create an instance of this unless you’re sure you have a message ot send. You can see a little more detail on what I found at Lastly, one big decision point was how to handle errors and track performance. While failed messages will certainly show up in HAT this does not help your typical developer who may not have access to the HAT database in a production environment. We opted for using the event log as well. Lastly instumentation was another issue that we didn’t find a lot of guidance on.

  2. mmckeown says:

    Thx Steve for your input! Sorry for the delay on the response (holidays).

    Can you explain in more detail where the spareness occurs in the documentation? What are the main issue you felt were lacking? I know you mentioned error handling and performance tracking, along with instrumentation, but where there others?

    – Mike

  3. Steve says:

    I would say those were the big ones. We probably struggled more with the design time aspects such as implementing our own editors but the examples were quite helpful. The run-time behavior was not too bad. It was mostly a matter of figuring out where to plug in our custom code. The big concerns were how to deal with errors, how to instrument the adapter, and how to ensure the custom code was testable. Best practices and the like.

  4. mmckeown says:

    Good stuff Steve. I will pass this onto the product team. thank you.

  5. jinishans says:


    Last project we’ve done in Biztalk 2004 and we’ve used the Sample File Adapter and customized it, but not the Adapter Framework. But, we know about it. Why there is no support for a SQL Adapter which can support Other DB’s also. Atleast in Adapter Framework if you provide a sample to use the .NET Data Providers, it’ll be better as Steve has done for them.

    Also, if there is sample for FTP adapter, it’ll be better. We can plug our own 3rd party FTP client and use it also. We had a requirement to download the file from a FTP Server in our last project. But, FTP does not support locking of file, because of which partial files are downloaded.

    What we did is modifed the File Adapter and did it. But, it took huge memory (we’re newbies in BTS). So, we dropped that idea. Because, to solve the issue, what we’ve done is, we’ve used a 3rd party FTP Client, and issues a rename command from the adapter to the remote file. If it fail, then, the file is still not uploaded by the other application in the ftp server and we’ll try to download once we’re able to rename it.

    Steve, can you share your sample adapter.

    With Regards,


    Wipro Technologies,

    Chennai, India

  6. I am ISV using Adapter Framework to develop a custom transport adapter, but it is not complete.

    Using the beta 2 docs, and the samples I have been able to get the adapter going.

    – The docs were really good explaining "adapter variables" — good stuff. But more info needed for the "loopback" scenario, basically I have a transport with an asynchronous message receipt — so what is recommendation to accomodate this.

    But now past the basics I have lots of questions which are not answered by the docs.

    – what to do when property validation fails — throw an exception, but is there any specific one to inherit from? There should be.

    – And if endpoint properties are invalid, then the adapter should disable itself, but exactly what api method to use?

    – more info on what to do when one message in a batch fails, should I modify asynctransmitterbatch?

    – how to suspend a message so that is is "resumable" vs "non resumable"

    – I want to override an endpoint property at time when my message is bound to the send port, not entirely sure how to do this in an orchestration — should the context be used?

    also — where do I log bugs for bts2006? Can’t find any obvious url. Thanks.

  7. mmckeown says:

    good stuff Jennifer. I will work at getting you an answer as quickly as I can. thanks.


  8. mmckeown says:

    okay Jennifer, here are the answers/further questions to your comments.

    – Loopback: Are you referring to receiving a response resulting from a send from BizTalk? If so, we have some samples around that already.

    – Property validation and exceptions:

    When property validation fails throw an exception. And somewhere catch it before you drop off that thread. On catching an exception if you have a Message then SetErrorInfo(exception) on that message – this will cause the error message to get associated with the message and you can see that in message-tracking. If you have no message – generally the case on the Receive side then you should call SetErrorInfo on TransportProxy. Both these calls will also result in an EventLog entry so you don’t need to do that.

    No need to inherit from any particular exception. The exception text is what you have to worry about. So, for example, you might like to put the text in resources – we do and we localize it.

    Not sure I agree “there should be.” A base class is somewhere to squirrel away reusable helper code – that’s cool but there are always many ways to do that. But more fundamentally any statement about inheritance is a statement about type relationships and type hierarchies. So you might build a type hierarchy if you where thinking about your error handling logic in a particularly polymorphic manner – for example handling errors of-this-type here and of-this-other-type somewhere deeper – this is very appealing but rarely implemented with such elegance. Today BizTalk doesn’t case about the type of the exception just that it’s an exception and it pulls the text out.

    – Invalid endpoints and which API to use:

    That API is TransportProxy.ReceiverShuttingdown.  Needless to say, this is for the receive side. It’s the receive side that you would want to shut down right?

    – on modifying asynctransmitterbatch

    If you are doing transactional stuff you might want to play at this level. Study the Transactional version of this class in the TransactionalAdapter sample. But otherwise you should be good to go with the one in BaseAdapter it handles all the error cases correctly.

    – on "resumable" vs "non resumable"  suspends

    There is a property called SuspendAsNonResumable it should be in the global property namespace. This takes a Boolean value and controls the behavior of the BizTalk engine.

    – on using the context to override the endpoint property

    Given the property sheet framework we live with the bts04 and bts06 there is no simple way to do this. So you should define a message property schema with your property in it and then have the adapter use that property rather than the static send port property if it is there on the message. In other words handcraft this per property in the adapter. Hopefully this makes sense.

    – No word yet on where to log BTS 2006 bugs. But if you are talking about documenation bugs I can help you.

    Kind regards


  9. jenzo says:

    Hi Mike, thanks so much for these answers.

    Please let me clarify a few questions a bit more…

    Property validation – this occurs when use set up an handler or endpoint using the property pages. So when the user enters data, the management class will validate before accepting changes. At this point if data is invalid, I throw an exception with a message. The resulting dialog box is just an "X" with the given message. The title of the dialog is "Error" but what if we wanted it to read "invalid data" or something. Just a thought.

    Invalid endpoints – if my send adapter decides it wants to shut down an endpoint because of a grievious error — what to call?

    And a new question

    – Is it possible to create more than one handler for a given adapter? The need is: if having a dynamic port, then there is no "endpoint" as such and all props need to come from the handler, plus the dynamic Uri. I have about 15 props, mostly about how to deliver the message and the dynamic URL will be only one of them, i.e. where to deliver the message.

        So If I can only have one handler instance, then the other 14 props are totally locked in. For example, I would like one handler for HIGH priority and a second handler instance for NORMAL priority messages, meanwhile the dynamic Uri is specifying the destination address.

    Thanks again for the answers so far, I if you can provide a link where to log bugs/feature request, that’d be great.

  10. Mark Bernardinis says:


    I am developing an adapter where I want the behaviour of the message to enter the suspended (non resumable) when all retries have been exceeded. I wrote the following section of code

    msg.Message.Context.Write("SuspendAsNonResumable", "", true);

    But the message is still entering the suspended (resumable) state. Could you please help with this? I am using the Base Adapter Class Library v1.0 base framework… is there any special place that I should be placing this code or is this incorrect what I am attempting to do? Thanks for your help.



  11. Mike says:


    I am working on getting you an answer to this shortly.  

    Kind regards


  12. MIke says:


    Here is a response to your questions. HTH.


    Normally on send side, since message is immutable, he will need to add the context property via UpdateProperty instead of just writing it. However, in this case it is a special property, we clear it right away when EPM gets it before passing onto adapter. But on the other hand, as long as this is set just before calling MoveToSuspendQ(), that setting would have been maintained.

    The idea is you set this on the message context – so that code looks OK. Having said that the scenario sounds like send side – we’d normally just do this on the Receive side – I’ve not tried it from the send side.  

    BaseAdapter 1.0 is the bts04 version of this code.  The code in bts06 ibase classes are significantly simpler and better tested.

    The property wil be ignored on bts04.

  13. Mark says:

    Thanks for your response. Unfortunately our company is using BTS04 so I am restrained in writing the BTS04 adapter using the version 1.0 of the base adapter source code. Are you aware of any techniques to do this under the BTS04?

    Not sure if this will work due to the amount of dev work that was done in BTS06 but do the base classes work in BTS04 and if they do is there a place to download them from?


  14. Danny says:

    I need to develope a custom sql adapter which will work asyncronously. Is this is already exist there or need to build custom adapter.

  15. akhilranjan1 says:

    I want to develop a custom adapter for SQL server so that i can create dynamic send port for SQL server.

    Is there any way to create this or is it already there?

    Please send me ideas on

Comments are closed.

Skip to main content