Having or not having read about the BizTalk basics, having installed the fresh and new instance of BizTalk Server 2010 we can finally start playing with it. In all examples I’ve seen in books or online, the first one is always with FILE Receive Locations moving a file from the source to the destination directory. No surprise, we’ll do exactly the same. Step by step, with all the errors that may arise, analyzing logs and finally getting it all working. I would like to avoid showing only 100% working examples as those are in real life the minority. There is always something that needs fixing, that we’ve forgotten or haven’t known about.
In order to do anything with BizTalk Server we need to launch its administration console. It’s an easy to use and fully functional MSC Add-On which is available configured from the shortcut in Start Menu.
We launch it simply by clicking. After a short while we can see the following window.
As I’ve already mentioned, the window looks like a MSC-Add-On for it’s actually one. Readers alerady familiar with basic administration work in Microsoft Windows Server should have no problems with managing BizTalk as well. In the next step we expand BizTalk Server Administration tree node. We can see that on our computer is already installed and configured on BizTalk Group representing installed BizTalk Server 2010 instance.
The tree expands into tree main subnodes:
- Platform Settings
Names are pretty self explainable. The most important for us is of course Applications node. We expand it.
What we find there are three preinstalled applications. There’s the one called BizTalk.System which will be referenced by all our custom applications. The question is: Why? The answer is to find in the BizTalk.System -> Schemas node. There you can find all the common XML Schemas that can come in handy in your projects. That’s why we should always consider BizTalk.System application as the starting point, or better: a parent, for all applications that we plan to implement in future.
BizTalk EDI Application is the one we should completely skip and ignore at this point. It contains an example of using BizTalk Server 2010 in Electronic Document Exchange (EDI).
BizTalk Application 1 on the contrary to the before mentioned, does nothing actually. It’s a completely empty application meant to be a container for our first steps and experiments with BizTalk. We will simply ignore this one too, and create a brand new one.
We right-click on the Application node and select New -> Application. In the window shown below we name our application after my blog’s address (just an example) and select make this the default application. After that we switch to References.
Here we can see the uniqueness of BizTalk. System application. It’s already referenced. This connection can easily be removed, but now we should leave it unchanged and click OK.
After clicking OK our application MusialTk should be already seen among the ones we’ve talked about before.
Before we can start configuring proper BizTalk Objects we should prepare the environment for our file system BizTalk application. We create a folder on disk in which we create two subfolders: in and out. IN folder is the one that we use to put files which should be read by BizTalk treated as messages and sent to the subscriber which will save it in OUT folder.
Once folders are configured, we go back to BizTalk Server Administration Console. We start from creating Receive Port with corresponding Receive Location which will be responsible for picking up a file from IN folder and passing it to BizTalk MessageBox.
We chose to create One-way Receive Port. This kind of port is used every time when the sending part (publisher) does not require a response in return for its publishing action. As analogy to One-way Receive Port we can consider void methods in programming languages. We call them for their side effects and not for their result, as they return nothing.
In the window that was opened after choosing to create One-Way Receive Port we can choose its name and specify of course authentication that will be used in order to obtain messages through this receive port.
In our case no authentication is required so we simply leave No authentication. An interesting option, which isn’t also used in this part of my tutorial, is Enable routing for failed messages. If we select this option, BizTalk Server 2010 accepts all the incoming messages even if there are not subscribers. This allows us to implement actions that could respond to messages that have no subscribers. An example of such an action is to create Send Port which subscribes for messages that have been marked as failed. In this case we can store them for future use, send notification e-mail to the administrator and much more. For now let’s leave it unchecked.
In the next step we switch to Receive Locations in order to create physical adapters which will supply our receive port with messages. What’s the most interesting: We can have multiple Receive Location for one Receive Port. What does it actually mean? It means that when we expect to receive orders for our internet shop, we can await the messages on the WebService, WCF-Service, Disk Folder, HTTP Connection and more more. All of them will be routed through the one Receive Port.
For now let’s create New.. (Receive Location). We give the Receive Location some logical name and we proceed to choosing its Type. In our case, from the very long list of available types, we choose FILE option.
All the other options we leave unchanged. The one that’s in my opinion, the most interesting is Receive Pipeline.
By default there are two available pipelines:
- PassThruReceive – does not treat messages as XML files, so no structure validation is applied. The message, file or any other data is simply passed through. No routing based on the message content is in this case available, as no XML data are parsed.
- XMLReceive – treats incoming messages as XML files. In this case structure validation is applied and when the message is not a properly built XML file an error is returned. IMPORTANT: NO XML SCHEMA VALIDATION IS APPLIED BY DEFAULT. It can be configured and we’ll do so in future.
In our case, as we work only with files, we choose PassThruReceive. Before we can click OK we have to configure our Receive Location. It should know from where the messages are to be picked up. We click Configure.
What we easily notice are two main fields to be configured Receive folder and File mask. We provide our IN folder path: C:\MusialTk\Part.2.2\in and change File mask to *.* (we decided not to limit ourselves only to XMLs). Other tabs we leave unchanged and click OK.
In the next window we simply confirm configuration we’ve just made clicking OK.
And now our Receive Port has a proper Receive Location.
We confirm clicking OK.
Newly created receive port is now available in the list. But it’s not everything we should do to make it working. As we know that Receive Port is only an abstract structure built on Receive Locations we should check if it’s everything OK with our Receive Location.
Indeed, IN-Folder-ReceiveLocation is by default disabled.
Let’s enable it. Right-click, and Enable. When everything is properly configured, in our case, when then folder exists and is available, we should see the Receive Location changing its state to enabled.
Although you may feel that there’s something missing in our set-up, let’s try to drop a file in the IN-Folder. Let’s create on our desktop a file named e.g. testFile.txt.
Now we can copy our file and Paste into IN-Folder. After pasting we expect the file to disappear as BizTalk Server should take it into its MessageBox. But actually the file stays.
Now it’s the right time to get used to analyzing BizTalk logs. We get back to our favorite BizTalk Server Administration Console, but this time we expand Event Viewer (Local) node. Next Windows Logs and Application. Among all entries we look for those with Source equal to BizTalk Server.
The error message is pretty much self explainable. But what we’ve done wrong. Lets right-click on our IN-Folder and choose Security tab.
Among all the entries there is no BizTalk User. However there is a group named Users which has a few permissions. When we look closer these are only Read & Execute permissions. They should be enough when BizTalk would only want to read the file. But once read the file is deleted by BizTalk so that it won’t be read many times. There’s no other solution than giving BizTalk user the proper permission. But let’s make it on the parent folder, I mean Part 2.2.
We click on Edit…
And finally we type in BizTalk. We can click Check Names too in order to check whether we provided the proper user name, but it’s not obligatory. We simply click OK.
In the next step we choose to select Modify (Write gets selected automatically). We leave Full control unselected. Then OK & OK.
IMPORTANT: When anything goes wrong (like in our case) then Receive Location that caused errors is disabled.
We right-click and select Enable. But a strange thing happens: It’s disabled again. That means nothing more than that we have another error. We check, yep the same.
The solution is fairly simple: give BizTalk user Full Control permission. We go back to Receive Locations and once again Enable. This time it stays enabled. Horray!
Our file disappeared as expected. But where is it now? See Application logs.
Happened exactly what we’ve expected. There were no subscribes so the message could not be routed. But when we have our publisher working, creating a subscriber is a piece of cake.
We’ve already created Receive Port with its Receive Location. The play publisher role in our Publish-Subscribe BizTalk Play. So we need to announce a casting for subscribers. There are many available candidates, some better some worse but we decided to cast Send Port for subscriber role. It’s a fairly simple play in which the subscribers stands patiently under the publisher’s window and awaits messages. The only thing he needs to do is to filter messages and catch only those to which he subscribed. In our case the subscription is based on the Receive Port name. We say: if you said it to me through IN-File-ReceivePort then it’s addressed to me.
We go back to BizTalk Server Administration Console, expand MusialTk application, and right-click on Send Ports node selecting New -> Static One-way Send Port
As you can see there are two kinds of Send Ports:
- Static – physically connected to the place, implementation and so on. For example in our case: physically connected to the OUT-Folder.
- Dynamic – can be parameterized for example from the orchestration. This allows dynamic changes of the destinating parties/locations.
In our case we choose a simple Static One-way Send Port.
We name it OUT-Folder-SendPort, once again choose Type FILE and other options leave unchanged. We click Configure.
We type in our destination folder location and leave other settings unchanged. Important we leave File name unchanged too. In BizTalk all the messages are treated as XMLs even though we are aware that the actual content of our incoming file (from IN-Folder) is not a well formed XML. We click OK & OK.
Newly created Send Port is now available in its Unenlisted state.
There are two available states of Send Ports:
- Enlisted / Unenlisted – a port is already registered as a subscriber, so no Routing failed errors are thrown. But messages are kept in MessageBox until Send Port becomes enabled.
- Enabled / Disabled – a port is enlisted and is working, which means ready to receive and process messages.
We right-clik on OUT-Folder-SendPort and choose Start.
Now let’s test our Application once again and paste our testFile.txt in IN-Folder. Once again it disappeared but once again we get Message Routing error. There are still no subscribers. We configured no subscription on the newly created Send Port. Let’s fix it.
Right-click on OUT-Folder-SendPort and Properties. We switch to Filters. There are no available filters as no were created. In this tab we specify so called filter which are then read by BizTalk Server to determine if there are any subscriptions for the message that has just arrived in MessageBox.
As we’ve already said before, we base our subscription in this simple example on Receive port name. So we choose Property and select BTS.ReceivePortName and in the field Value type the name of our Receive Port, that is IN-Folder-ReceivePort.
We confirm clicking OK. Now we’ve successfully set up fully functional subscribers for messages which are sent through IN-Folder-ReceivePort.
Lets paste once again our testFile.txt into IN-Folder. Disappeared? Great! Now let’s check out OUT-Folder.
Amazing, huh? It works! Our file has the name corresponding automatically generated MessageID (.NET GUID).
And in spite of the fact that our out-file has an xml extension, its content is equal to the content of the in-file.
We did it. We’ve just set up and tested our first simple BizTalk application. If you’re ready for more, there’ll be more examples & more fun soon.