Managing RFID Applications
A BizTalk Server RFID solution can consist of one or more of the following:
- .NET applications using the command-response programming model
- RFID processes
- Event handler libraries
- Business rules used by the Business Rule Engine (BRE) event handler
- Event handler libraries
- Mobile RFID applications
- ISV or custom-developed applications
This topic focuses on the management of the RFID business process.
An RFID process provides an application host for asynchronous processing of RFID events. The RFID process health impacts the processing of RFID events relevant to your business scenario. For example, if the process is “Stopped,” then no processing is happening.
Checklist: RFID Process Health
Check that the RFID process is in “Started” state
Check for errors from event handlers
Check for process restarts
The process state can be one of the following:
- Event collection mode
All processes should be typically in the started state unless an administrator has explicitly stopped the process for maintenance operations.
An RFID process in event collection mode indicates a problem where an error-handling policy has triggered the process leading to this state.
An error occurs in the RFID application when:
- An event handler throws an uncaught exception.
- An event handler takes a very long time to process a single event. This event is considered as a hung event.
- The RFID process is restarted.
- The IIS worker process is restarted.
- The event is put into the suspended queue for that RFID process.
Note The GetNextErrorEvent method is the only supported way to extract the event from the suspended queue. After you resolve the issue that caused the action, the event must be resubmitted to the process for further processing.You can download a sample that uses this API at http://go.microsoft.com/fwlink/?LinkID=106351. If you run this sample, the error events are permanently removed from the suspended queue and need to be handled correctly.
Event collection mode
If the RFID process has been restarted five times within five minutes as part of error handling, then the RFID process is in event collection mode, which is a paused state, and the behavior is as follows:
- Connections to devices are maintained.
Events are directly added to the process queue.
- No processing logic from the event handlers is applied. When the process mode is changed to Start, the events are processed.
|Event collection mode is not available when the RFID process is in Express mode. The RFID process goes to the stopped state and the device connections (for devices that are bound) are closed.|
Error policy-related knobs
- SingleEventProcessingTimeout. This is the time required for an event handler to process a single event. If an event takes longer than the value defined in SingleEventProcessingTimeout, the event is considered as a hung event.
- MaxHungEvents. MaxHungEvents counts the number of times when the event handler’s processing time is more than the time limit that is set in SingleEventProcessingTimeout. The default value of MaxHungEvents is 0.
- ErrorPercentageThreshold. If the percentage of errors that occur crosses the limit that the developer specifies in ErrorPercentageThreshold, BizTalk Server RFID attempts to restart the process engine. The default value of ErrorPercentageThreshold is 0, which means that every error causes the process engine to restart. If the value is 100, the process engine will never be restarted.
RFID Process Errors
Each RFID process has a dedicated log file. The log file can be found in the %RFIDDATADIR%\Processes\<RFID Process Name> folder. For easier debugging we recommend that the event handlers use the RFID process log:
protected ILogger eh_log ; eh_log = RfidProcessContext.GetLogger(name); eh_log.CurrentLevel = RfidProcessContext.GetLogger( container.ProcessName).CurrentLevel;
The overall log file management follows the standard BizTalk Server RFID log file management as described in Managing Log Files.
For backing up the RFID process log files, refer to Log Files.
Log Parser (http://go.microsoft.com/fwlink/?LinkId=150653 ) is a tool for reading through log files.
Inside the BizTalk Server RFID service, errors happening in the RFID process can be seen in the Windows event log. This can be viewed by doing a FilterLog as follows:
- From Event Viewer, browse to Windows Log and then under it Application.
- Right-click and use the following values for FilterLog, as shown in the following figure:
Event sources = MSBizTalkRFID and Task category = ProcessManager
RFID Process Restarts
For a process restart, the event log should have an entry like:
"The RFID process engine <RFID Process Name> encountered an error of type ThresholdBreached. The service will attempt to restart this process engine automatically, unless this was because of a known fatal error"
The BizTalk Server RFID service log should also indicate the RFID process restart.
The RFID process can be configured in different operational modes as required by the application. These are exposed as "Tag Processing Modes" when using RFID Manager and exposed as "MessageHandlingReliability" from the object model.
|This value must be set when creating the RFID process and cannot be modified after that.|
The following sections describe the semantics of the modes and when to use them.
When the tag processing mode is set to Transactional, BizTalk Server RFID handles the events within the scope of a transaction after BizTalk Server RFID queues events that it receives from physical devices, so that they are never lost because of errors.
BizTalk Server RFID starts a new transaction for each event in the queue. The scope of each transaction includes dequeuing an event from the event queue and processing the event by using event handlers. If an event handler has an unhandled exception, or if any other error occurs during event processing, the transaction is aborted and the event goes into the suspended events queue.
If an event handler interacts with a resource manager (for example, a database) that supports transactions, by default the event handler’s work is also part of the transaction. For example, if an event handler inserts a row into a database table, but a subsequent event handler has an exception, and the transaction is aborted, the first insert is also aborted.
The Message Queuing queue created for the RFID process uses the transactional mode. For more details, see MessageQueue.Create Method (http://go.microsoft.com/fwlink/?LinkId=153202).
Use this mode when event processing requires transactional semantics. This is useful when event handlers interact with the following resource managers:
Any resource that supports system transactions or COM+ transactions can participate in the transaction. Well-known resources that can participate in the user interaction are as follows:
- SQL Server 2005 SP2 or SQL Server 2008
- Message Queuing
- Most current database management systems (DBMS)
|This is the default mode for an RFID process. Operating under this mode has performance implications and should be used only when the transactional semantics are required in your scenarios.|
When the processing mode is set to Reliable, BizTalk Server RFID creates the Message Queuing queue (used by the RFID process) to back up messages on disk.
By default, Message Queuing (also known as MSMQ) stores some messages in memory for increased performance, and a message may be sent to and received from a queue without ever having been written to disk. This is not normally a problem, and it is completely transparent to you as the developer, but if the Message Queuing service were to unexpectedly terminate due to a hardware or software failure, or due to some external circumstance such as a power failure, messages stored only in memory will be lost forever. You can control this behavior, forcing Message Queuing to store a message to disk, by specifying that a message should be recoverable.
For more information, see Reliable Messaging with MSMQ and .NET (http://go.microsoft.com/fwlink/?LinkId=153207).
This is the recommended mode to set up the RFID process to make sure events are not lost in case of in-memory crashes.
This setting creates the Message Queuing queue to maintain the events in-memory only.
In normal conditions, having Message Queuing operate messages only in memory should not be a problem. Use this mode only if the system can sustain the message losses mentioned in the previous section and when high throughput is required.
The performance white paper explains the throughput numbers when using these modes. Refer to the "Design and Development Phase" section in BizTalk RFID: Capacity Planning and Performance Tuning (http://go.microsoft.com/fwlink/?LinkID=150400).
An event handler is the execution logic that resides within an RFID process as part of the component bindings. For more information, see What Are RFID Event Handlers? (http://go.microsoft.com/fwlink/?LinkId=156745).
|If specific device operations are performed from an event handler, then the RFID Worker Process account should be added to the RFID_USER group and additionally to the device administrator or local machine administrator group depending on the operation performed. Refer to BizTalk Server RFID: Web Service Calls for details.|
Event handlers can expose configuration knobs that can be set by the administrator. The application developer defines the semantics of a property; for example, the SQLServerSink event handler exposes the connection string, command time-out, and so on. Each property has a set of metadata that describes the values it can take.
From an operational standpoint, we recommend that you understand the configuration knobs exposed by an event handler and understand how to use them. If the event handler exposes any event batching or time-out configuration knobs, they need to be set up correctly depending on the operational environment.To view event handler metadata
In RFID Manager, for each RFID process, do the following:
Click the Browse tab.
Under Component bindings, select the event handler.
In the right pane, you can view the properties of the event handler.
Click each property to display its metadata.
|This metadata is set up by the event handler developer. We recommend that rich metadata be exposed. For details on exposing this metadata, see How to Expose an Event Handler to BizTalk RFID (http://go.microsoft.com/fwlink/?LinkId=156752).|
This section lists the set of tools that can be used to manage the RFID process.
RFID Manager: Viewing RFID Process Summary Information
The RFID Manager administration tool can be used to view the RFID process state and diagnostics information. The MMC snap-in can be used to connect to multiple BizTalk Server RFID runtimes in your deployment.
- Process name
- Tags read (number of tags that the process read)
- Process uptime
- Error message
- Component that caused the error
- Logical device that caused the error
- Time at which the error occurred
RFID process-specific information
This information can be viewed from the RFID Manager Processes pane by clicking the specific RFID process, as shown in the following figure.
Scripts: RFID Client Console
The RFID Client Console can be used to script and obtain the process status. The output from the RFID Client Console is raw text and has to be parsed.
For details about how to use this tool, see RFID Client Console Commands (http://go.microsoft.com/fwlink/?LinkId=156754).
RFID Manager: Configuring the RFID Process
RFID Manager can be used to configure the RFID process and set the correct values for the various parameters described in the previous section.
For more information, see <Process> Properties Dialog Box (http://go.microsoft.com/fwlink/?LinkId=153216).
The RFID administrator can export RFID processes to an .xml file and import from the .xml file to BizTalk Server RFID. The import and export features are helpful while you are transferring processes from one BizTalk Server RFID server to another, or during deployment to multiple computers.To export a process from BizTalk Server RFID
In the console tree, right-click the Processes node, and then click Export to display the Export Processes dialog box.
Select Export Bindings to export device- and component-related binding information.
From the Available processes list, select the processes to be exported, and click Add. You can click Add All to export all processes.
From the Selected processes list, select a process and click Remove if you do not want to export the process.
In the Name and file location box, type the name of a file, or click Browse to specify a name and location of a file.
Click Start Export to export processes and related information to the .xml file. To interrupt and stop the export procedure, click Stop Export.
Information about the procedure is displayed in the Export Summary area, and errors can be viewed in the Message column.
In the console tree, right-click the Processes node, and then click Import to display the Import Processes dialog box.
In the Source XML file box, type the name of a file, or click Browse to specify a name and location of a file.
Select Import Bindings to import processes and process-related bindings.
Select Overwrite Processes to replace an existing process by a process (with the same name) from the .xml file.
Click Start Import to start importing processes and related information from the .xml file. To interrupt and stop the import procedure, click Stop Import.
Information about the procedure is displayed in the Information area, and errors can be viewed in the Message column.
The imported processes appear in the results pane of the Processes node.
The import and export processes do not manage the private event handler assemblies. You need to move the event handler assemblies separately. While exporting from RFID Manager, you should see the following pop-up message.
The private event handler libraries can be found in the %RFIDDATADIR%\Processes\<ProcessName>\bin folder. Copy the private event handler assemblies to the same location in the new folder after the export operation.