MBVQueryBuilder Quick Help

jpierauc — Wed, 15 Apr 2009 08:01:00 GMT

This doc below provide some documentation on MBVQueryBuilder tool , explaining what is this tool and why it exists and what it allow to do.

1) Presenting MBVQueryBuilder and its concepts

What is MBVQueryBuilder ?

This tool allow to create quickly and easily additional queries for MBV tool
This tool can create and update a Query Repository XML file with the all queries you will create and allow also to generate the queries you want in an XML MBV Extension file starting with name "MBVEXT".

Why MBVQueryBuilder ?

MBV use a custom Health Check engine I developed ("MyHC" Engine) which is easily extensible in tem of queries and rules.
This extensibility is made possible via any XML file starting with name "MBVEXT" and located in same folder than MBV.

These MBV Extension File contain additional custom queries (with their rules if exist) which will appear in additional Queries tabs in MBV gui interface.

To generate easily and quickly such MBV Extension XML files, it became obvious to create a tool to do it.

What is a MBV Query and what it contains ?

An MBV query is an object containing following information :

Main Query information :

- Internal ID: guid
- Category : category of the query
- Caption: visible caption of the query, ex: "List of Send Ports"
- Comment : Description of the query
- Source and Versions : Information about the source and version of this Query
- Type: SQL, WMI, .BAT, .CMD,.VBS, Other
- Target Type: server or Db to target executing the queries
- Target Name: Visible target name in MBV tool gui
- Body: Text of the query (ex: "Select @@Servername")
- Different attributes: selected by default in MBV gui interface, log a report, etc...

Rules:

A query can contain 0 to N Rules containing themselves 0 to N Conditions and each rule if validated can execute some actions.

A rule is so a set of conditions checking some values in each row of a report of a query, which is just in fact a table where you have columns as SQL fields for example and rows as records.

Each condition containing some references to a column is evaluated per row in the report.
Each condition containing no references to columns like "%ROWCOUNT% > 100" will be evaluated first and only once of course.

So a Rule object is composed of :

- Internal ID: guid
- Caption: Rule caption visible in MBV tool
- 0 to N Conditions
- Actions

A Condition is composed of predicates :

- A value to check, which can be either a reference to a report value in a specific column, or any other value (like %ROWCOUNT%)
- A value to trigger an action
- A Boolean specifying if comparison will be case sensitive or not

Possible Actions are :

- Write an entry in the Summary Report section with 0 to N link and 3 possible level of warning
- Write an entry in the Topology Report section
- Call a custom .NET function in a custom dll
- Assign a value to a global property (see below for "Properties")

Properties:

Each query can have 0 to N custom properties (i.e variables) identified by an ID, a caption, one value, and some attributes.

When specify in a body, caption, Summary Report entry, etc.. with syntax "'%<Property ID>%", MyHC engine will replace at runtime this "macro" by its corresponding value.

You can also decide to have a query property visible in MBV gui. In this case, the property caption and its current value will appear in MBV interface (right pane) when selecting the query in the Queries list, allowing you to enter a new value.

Custom processing Functions

Each query can (it is completely optional) to have custom .NET functions implemented in custom dll and called automatically by MyHC engine at different stages:

- before the query will be proceeded by MyHC engine
- to execute the query
- before each query report is populated
- after each query report is populated
- After the query processing is finished

These functions are interesting mainly when you have type of queries noty supported by MyHC engine or if you want to add your own logic at different stages of the query processing

A sample of a C# project implementing such custom DLL and functions is provided with MBVQueryBuilder

Which type of queries we can create in MBVQueryBuilder ?

MyHC engine that MBV uses provides implementation to execute automatically SQL, WMI, BAT.CMD and VBS queries.

By "automatically" I mean that by providing just the body of a SQL queries, the HC engine can execute them without having to provide any code or logic implementation. It is the same for WMI, BAT.CMD and VBS queries.

For .BAT,.CMD and VBS queries, they can be executed only locally on the machine where MBV is running, as opposed to SQL or WMI queries where you can target remote servers.

To execute automatically .BAT, .CMD and VBS queries, MyHC engine just create on the fly a temporary file and paste the body inside before to execute a CMD.exe or CSCRIPT.exe process and intercept the console output.

MBVQueryBuilder and queries Targets

Each Query has a corresponding Target Type and Target Name :

- The Type allow MyHC engine to know which server to target executing the queries, ex: MsgBox Servers, MsgBox Dbs, DTA Db, Mgmt Db,ALL Servers of the BizTalk group, SQL servers of the BizTalk group, etc...

- The Name is visible in the Queries List in MBV gui interface in the last column

If you select Target Type ending with "Server" or "Servers" for SQL queries, you can enter a specific Database name (ex: "Master") or if you let it empty, MBV engine will use automatically the corresponding BizTalk Database name, ex: "BizTalkMsgboxDb" for a MsgBox server

Queries Columns:

For querie which are not SQL or WMI, like .VBS, .BAT, .CMD, or OTHER you can specify the columns name the query report will have and also specify the delimiters of query output to use to identify the columns.This fetaure is interesting mainly for .BAt, .CMD, or .VBS to display the console output in a table formated way.

Global Properties:

In the same way you can define properties for Queries, you can also define in MBVQueryBuilder from 0 to N custom Global properties identified by an ID, a caption, a default value, and other attributes.

When specify in rule conditions, query body, query caption, Summary Report entry, etc.. with syntax "'%<Global Property ID>%", MyHC engine will replace at runtime this "macro" by its corresponding current value.

You can also decide to have a global property visible in MBV gui. In this case, the global property caption and its current value will appear in the Global Properties tab of MBV interface (left pane) allowing you to enter a new value.

These global properties are some sort of global variables that you can create and reuse everywhere in queries or rules allowing you to customize your queries.

MyHC engine provide by default some internal global properties that you cannot remove in MBVQueryBuilder but you can change their default values for some of them. Some of these internal global properties have their value changed dynamically by MyHC engine and will contain for example :

- the current physical targeted server name
- the current targeted DataSource name
- the current targeted database name
- the current type of targeted server (is it BizTalk Server, a SQL Server)
- etc ..

Query Categories:

Important: This feature is implemented in MBV only since version 10.13

A Query category allow to better sort and group queries.

When you want to create a query in MBVQueryBuilder, you can specify its category, whatever it is an existing one or a new one

Each Query Category is composed of :

- an Internal guid
- a Name
- a Type: “Important”, Optional”, “’Custom”
- 1 to N queries (see above for Query description)

At startup, MBV will load the categories of each query either from its embedded Queries Repository XML or from external XML Extension Files and it wil create a many tabs as it find categories.

Each Important category will have it name shown in bold in MBV, and for each categories found in a custom MBVEXTxxxx.XML file, MBV will create the corresponding tab in blue color to specify that it is a custom category

Once created in MBVQueryBuilder, a category will appear in the Categories List in the tab "Categories".
You can there change its name and sort them. The order will be so preserved in MBV tool when it will create corresponding Queries tabs.

Each category name will be present in the HTML report before the list of its queries? with also its category type;

2) Using MBVQueryBuilder :

MBVQueryBuilder Dialog Box is composed mainly of 3 parts :

- The tab pages part consisting of 7 top tab pages divided in 5 for settings of the current query, and 2 for Categories and Global properties settings.

- The queries List View part contain the list of queries that you created with their information summary

- The bottom control buttons allow to :

o add a query

o remove a query

o Load another query repository file

o Test the queries which are checked in the List View

o Export into an Extension XML file the queries which are checked in the List View

How to create a fresh new Query ?

- Select the Query Type you want in the corresponding ComboBox at bottom of the tool Dialog box

- Select the Query Category you want in the corresponding ComboBox at bottom of the tool Dialog box

- Click on the button "Add:".

- A File Dialog Box will be opened inviting you to chose the name of XML file representing your queries repository.

- A new query will be then added in the Queries List View with its summary of information and its main information will be visible in the "Query Main Info" tab page where you can there change lot of its information like its caption, comment, Target type, etc...

A default query body will be filled as sample so you will have to change it

Once you finished all your changes on this page, remember to click on "Commit Changes" red button to commit these changes in the query and update the Repository file..

How to sort created Queries ?

The two arrows on the right side of the queries List View allow you to sort the queries in a same category.

Sorting a query allow to change its order of presentation in MBV queries List but also its execution in its category : It can be important for example to execute first a query before another one.

Clicking one of this arrow will so move up or down the query in its category (only !)

How to add Rules to a Query ?

- Select the Query in the queries List View

- Select the "Query Rules" tab page
A new rule is created with a default caption that you can change

- Select the "Rules Conditions" tab page and add your conditions (see Conditions above).

- Select the “Rule Action Types” tab page to specify type of actions to trigger if the rule is evaluated^

- Select then the other Rule tab pages to fill the actions information. They are quite explicit themselves.

In each predicates of a condition or fields of action tabs, you can enter any query custom properties or global properties in the form “%<prodID>%

- When you finished to fill all rules settings, remember to click on “Commit Changes” red button at bottom of the Rule page

Notes:

To fill correctly conditions and actions and have a detailed idea of the type of information and rule you can create, I suggest strongly to select some any native queries in MBV tool itself and display their rules details (right pane when a query is selected)

How to add Query Custom Properties ?

- Select the “Query Custom Properties” tab page

- Click on button “Add Prop” to add a new property
A default prop ID, caption and value will be filled that you can by double-clicking on each item.

- if you want to make a property visible in MBV tool gui then set to “True” the attribute “Visible in HC tool”

- The two arrows on the right side of the List View allow you to sort the properties. It can be important to specify an order if they are flagged to be visible in MBV

- once you finished your changes, remember to click on “Commit Changes” red button in this page to update the Repository file.

How to add Query Custom Processing functions ?

Important Note:

Filling these function names is optional if the query type and body is supported natively by MyHC and if the rules you want to implement can be implemented completely using conditions in Rules tab page.

- Select the “Query Custom Processing” tab page

- Fill the name of the dll implementing the custom functions (can have or not .DLL)

- Fill the name of the different .NET functions implementing your logic.
These functions will be called automatically by MyHC engine when it will be the time to execute this query.
These functions do not accept arguments and return value.

The main important functions is the one called to process the query. Indeed, if it is filled, MyHC engine will not try to automatically execute your query body and will depend only of this custom functions to do the query job.

If you need to create such DLL, I recommend strongly you to look at the sample of C# project “SampleExtDLL” implementing a such DLL and functions, provided with MBQueryBuilder

How to add Custom Global Properties ?

- Select the “Global Properties” tab page

- Click on button “Add Prop” to add a new property
A default prop ID, caption and value will be filled that you can by double-clicking on each item.

- If you want to make a global property visible in MBV tool gui then set to “True” or “True – in bold” the attribute “Visible in HC tool”

- The two arrows on the right side of the List View allow you to sort the global properties. It can be important to specify an order if they are flagged to be visible in MBV in the Global properties list

- once you finished your changes, remember to click on “Commit Changes” red button in this page to update the Repository file.

How to Test immediately the queries you created?

- Check the queries in the List View you want to test

- Select the targeted BizTalk Mgmt Server and BizTalk Mgmt Db

- Click on the button “Test Checked Queries” which will be enabled

- you will see some activity in the status bar in yellow and Internet Explorer will be started to display the temporary HTML report created showing the report output.

How to Export some queries from your repository into an Extension File usable by MBV tool ?

- Check the queries in the List View you want to Export

- Click on the button “Export to Query Extension File” which will be enabled

- A File Dialog box will be opened to invite you to select the targeted folder for this Extension XML file.

- If you have SQL queries to export, a Warning message will be displayed alerting that creating SQL queries targeting BizTalk Dbs can be dangerous in term of performances or integrity.

- Then if the file is correctly saved, a message will be displayed to confirm it

Important Note:

You need to be sure the Extension File will begin with “MBVEXT“ to be seen as Extension file by MBV tool

If you copy then this produced file in the same folder than MBV, then MBV will load your queries at next startup and will add them in their corresponding blue category tab !

How to load an existing queries Repository ?

- Click on the control button "Load/import other Repository" and browse for the XML repository file

- A message box will be then displayed asking you to replace your working repository by the new one, or to append in your working repository all the queries of the selected repository (Append mode).

- once choice is made, your working repository will contain the new queries loaded

My Biztalk Tools blog : MBVQueryBuilder help

MBVQueryBuilder Quick Help