Milos Blogs

Milos has always provided features around exception handling. In this upcoming build however, we have formalized a lot of the functionality (and added to it as well) to create two distinct sub-frameworks:

The idea is the exception logging framework is pretty simple: Whenever an exception occurs that remains unhandled, that exception can be "published" to the exception framework via a so-called "Exception Mediator" object. This object receives the exception and then passes it on to all kinds of interested listeners that can be registered with the mediator. Such listeners could be UI components to show exception information to the user (listener as well as UI components are provided by default and can be extended), or the information can be emailed to an administrator, or perhaps the information needs to be logged. The framework also includes components that can be used to retrieve detailed exception information such as an exception hierarchy or the current call stack.

The latest Milos version has a pretty neat enhancement in the business entity model: Sub item collections are now available as generics. Here's why that's cool:

Here is a small feature I really hope everyone appreciates, considering how hard it was to support it in a nice way: All sub item collections in Milos now implement IBindingList, which is a fancy way of saying that they can now be bound to pretty much anything that supports data binding.

In the past, most of the Milos controls supported binding to sub-item collections, but with third party controls, it was hit and miss. Adding support for this interface (in addition to the interfaces we supported previously) pretty much covers the whole range now.

Here is a new feature that only some people will need, but those who need it really do... ;-)

The Milos BusinessObject class features a SaveTable() method, with takes a DataTable as a parameter (among other things) and can then (by means of using various DataService features) simply persist all the changes in the data table back to the database server (whether that's SQL Server or some other database technology). This feature is used extensively by the BusinessEntity infrastructure (among other things). So for instance, when you load a business entity that has a master table and several child tables, each of the tables inside the entity is saved using the SaveTable() method.

In this example, the first SaveTable() operation is limited to the ContactID, FirstName, and LastName fields. Also, the primary key for the Contacts table is really ID, so we create a map for that. (This works for all fields, not just primary keys). If that save is successful, we perform a second save operation for the remaining fields. Not that in the second operation, we pass a true as the last parameter, which flags the data table as unchanged in memory (this is not done after the first save, since other changes still exist).

This is a pretty small item, but I find it useful in a lot of scenarios: There now is a new ArrayContainsString() method on the StringHelper object. It provides a quick way to check whether a certain string array contains a certain string, and it can do so in a case insensitive fashion:

Here is a small but nice tweak: When using navigation UIs, in particular the Office application forms, or the Developer Express application forms, Milos now supports automatic updates of the windows title (the secondary title, actually), from the pane's caption (the pane the user navigates to). This behavior is optional, and can be controlled by means of the UpdateWindowSubTitleFromNavigation property, which can be found on all app form classes.

Note: Related to this change is an update to the INavigationHost interface, which now features a NavigationCompleted event. If you implement this interface somewhere, you simply need to add that event to your implementation as well. The code required to do so is simple:

As some of you may know (although not all... which is what we are trying to address), the Milos DataService classes provide a simple way to query multiple records by multiple field names. For instance, if you want to query all customer with a last name of "Pronger" and a first name of "Chris" and active status, then you have been able to simply do this (in a business object):

This is nice, but a lot of people do not know that this functionality exists. Besides, there really is no reason why people would have to know about this somewhat hidden method on the DataService. For this reason, we added a few convenience methods right on the business object that are easier to discover:

string[] fieldNames = new string[] { "FirstName", "LastName", "IsActive" };
object[] parameters = new object[] { "Chris", "Pronger", true };
IDbCommand command = this.GetQueryCommand("Customers", "*", fieldNames, parameters);
DataSet customers = this.ExecuteQuery(command);

string[] fieldNames = new string[] { "FirstName", "LastName", "IsActive" };
object[] parameters = new object[] { "Chris", "Pronger", true };
DataSet customers = this.Query("Customers", "*", fieldNames, parameters);

It's been a while, but let's continue with the series on Milos and O/R Mapping. This time around, discussing Stored Procedure calls.

On the last installment of this series we've seen how to execute queries by running individual SQL statements (dynamic SQL). Executing Stored Procedures is not that much different: the main difference is that instead of using the ExecuteQuery method, we use the ExecuteStoredProcedureQuery method. For example, the following method in a business object would execute a stored procedure named GtPaymentsList:

public DataSet GetPaymentsList()
{
   IDbCommand command = this.NewDbCommand("GetPaymentsList");
   command.CommandType = CommandType.StoredProcedure;
   return this.ExecuteStoredProcedureQuery(command);
}

In case the stored procedure only processes some data and does not return anything to the caller, a method such as the one below will do the job of calling the stored procedure:

public void ProcessPayments()
{
   IDbCommand command = this.NewDbCommand("ProcessPayments");
   command.CommandType = CommandType.StoredProcedure;
   this.ExecuteNonQuery(command);
}

Another aspect of using stored procedures is that we may want all data access in our business objects to go through stored procedures. By default, when we use business objects and entities, Milos uses "individual commands" (dynamic SQL), which means it creates the SELECT, UPDATE, INSERT, and DELETE commands on the fly, depending on what the business object needs. Alternatively, the object can be set so that instead of creating SQL on the fly, Milos can look for Stored Procedures that follow a naming convention (we have code generators that create the necessary stored procedures). In order for that to work, all the developer needs to work is to code-generate the stored procedures, and configure the business object class, by adding the following line to the Configure method:

this.SetDataAccessMethod(EPS.Data.DataRowProcessMethod.StoredProcedures);

Milos can also be set so that the only data access method permitted is through stored procedures (which means that anything going through the data access layer has to be a Stored Procedure call). This can be set by adding the following configuration setting:

<add key="AllowedDataMethod" value="StoredProcedures"/>

That is it for now. :)

This upcoming build of Milos has some enhancements to all our grid controls that I know some of you have been waiting for:

Today or tomorrow, we will have a new Milos build. It includes a number of improvements (and some fixes) for WinForms databinding. (Some of which have been discussed before).

Not quite databinding, but still related: Milos data edit classes have been cleaned up a bit and optimized. We also added quite a few convenience methods that make it easier to reload data and the like.

We've created a bunch of videos to help us training new team members on Milos, and we figured these videos should also be helpful for our clients who are using Milos, as well as for those who'd like to check out what kinds of things are part of Milos. Below is a list of the videos currently available, in the respective order they should be watched. We are going to have more videos coming up soon. Stay tuned!

If there are things that you really would like to see explained in videos, please send us an email, and we will definitely consider it.

One of our main tools in Milos has always been our Business Object / Entity generator, that's available within the EPS Developer Services tool. That feature had some crucial limitations, though, so we've revamped it, including a number of fixes and improvements that we are sure a lot of users are going to appreciate. I'll list some of them here:

The main point is: the new generator gives us everything we used to have, plus a LOT more, so this is definitely the way to go moving forward. There is only one thing we don't have on the new tool yet: it doesn't auto-update yet. Since it's a VS plug-in, we couldn't just use ClickOnce out of the box. So, if you're creating and working with business objects and entities, send me an email soliciting a copy of the plug-in, and I'll send it to you (of course, you have to be a Milos user to request it. My email is my first name at eps-software.com). I'll put you on my mailing list to receive updates, until we get the auto-update feature into the plug-in.

Also, the installation and usage of this plug-in has been documented in videos. I'll post a blog entry about this shortly. Make sure to check it out!

Milos controls support native data binding. It has been like that since the beginning of (Milos-) time. So for instance, if you want to bind a textbox to a property on a business entity, you can simply set up the binding by specifying the name of the entity and property you want to bind to, using the ControlSource property of the textbox.

Note: This feature has been implemented and has undergone almost complete testing, so it will most likely show up in the next Milos build...

Following the series about Milos ORM capabilities based on this article, up next is the support for Static and Dynamic Queries. Milos does support both.

Essentially, every business object class inherits an ExecuteQuery method. This method takes a Command object. The SQL statement can either be defined during compile-time, with only the parameters filled in at runtime, or any other part of the statement could be built on the fly (like the WHERE clause, or the ORDER BY clause). Below are some ways one could execute queries from within a Milos Business Object.

Simple Query

IDbCommand command = this.NewDbCommand("SELECT * FROM Customers");
DataSet results = this.ExecuteQuery(command);

Simple Query with Parameter

IDbCommand command = 
        this.NewDbCommand("SELECT * FROM Customers WHERE PK_Customer = @PK");
this.AddDbCommandParameter(command, "@PK", someGuid);
DataSet results = this.ExecuteQuery(command);

A few things to notice so far:

We program to the ADO.NET interfaces such as IDbCommand, instead of programming to the concrete implementations, such as SqlCommand, or OracleCommand;
We use Factory Methods to create things like the command object or the parameter objects (NewDbCommand and AddDbCommandParameter methods, respectively).
The ExecuteQuery method wraps the calls out to the data services layer to deal with connections, data adapters, or anything else that is specific to the data service being used, which can be configured either during runtime or compile time.
Since the command text (the SQL statement) is passed as a string, it can be built dynamically depending on some criteria gathered from the user/application. Of course, the database security will prevail, and if a dynamic SQL is created to access some database object that the current user does not have access to, and backend will block it.

Helper methods for simple queries

For some simple queries, one can use some of the helper methods provided by the Milos Business Object. The benefit of using such methods is that we let Milos decided whether to build the SQL statement to be sent to the database, or to call Stored Procedures instead (depending on how the business object is set to process commands). That makes it also easier to swap between using direct SQL statements and stored procedures, or even swap between using different backends, such as SQL Server or MySQL. See some examples below:

Getting all records from a given table

DataSet results = this.QueryAllRecords("Customers");

If the business object is set to process commands using "IndividualCommands", Milos will create the CommandText as SELECT * FROM Customers. On the other hand, if the object is set to use "StoredProcedure", Milos creates a CommandText such as "milos_getCustomersAllRecords". The prefix ("milos_") is configurable, and the other parts of the name of the stored procedure follow a naming convention so that Milos knows what store procedure to look for (we have tools that generate those stored procedures for us!).

The QueryAllRecords method also allows for some customization of what gets retrieved:

DataSet results = 
      this.QueryAllRecords("Customers", "PK_Customer, CustomerName", "CustomerName");

Milos would create the following statement for the call above:
SELECT PK_Customer, CustomerName FROM Customers ORDER BY CustomerName

Of course, if the business object is set to use Stored Procedures, then the list of fields and ORDER BY clause on the method call are ignored, and the query in the stored procedure dictates the results.

Retrieving a Single Record

DataSet result = 
    this.QuerySingleRecord("Products", "PK_Product, ProductName", "PK_Product", 10);

Milos translates the call above into this:
SELECT PK_Product, ProductName FROM Products WHERE PK_Product = 10

Retrieving Multiple Records by a given Key

DataSet results = 
    this.QueryMultipleRecordsByKey("Customers", "CustomerName", "State", "TX");

The call above is translated into this:
SELECT CustomerName FROM Customers WHERE State = "TX"

This helper method is also great to get all the children rows for a specific parent, like this:

DataSet results = 
    this.QueryMultipleRecordsByKey("Orders", "OrderDate", "FK_Customer", someGuid);

that translates into SELECT OrderDate FROM Orders WHERE FK_Customer = someGuid

On the next post, we'll talk a little more about Stored Procedures. Stay tuned!

I have personally be using CodeRush for about 2 years now, and I've been creating custom templates for some things that I do all the time, both for .NET in general and for Milos things. Since we're now getting other EPS developers to use CodeRush too, and I know there are many of our clients also using CodeRush and Milos, I'll be sharing here my custom templates. This is important for both beginner Milos users learning how to use the framework, as well as for advanced users who already know what to do and want to do it quickly.

You can download our custom templates here. There is a 6-minute training video on how to share templates among developers here. A brief how to goes here:

Here's a list of some the templates we currently have, and what they expand to (I will not list all of them, since some I may still be tweaking or may end up droppng it from the list). Notice that everything in italic on the expansion indicates the pieces that the developer has to key in (the template will usually create stubs for it if possible):

IDbCommand command = this.NewDbCommand("select * from SomeTable");
return this.ExecuteQuery(command);

Usage: same as "eq" template, except that this one will add the necessary call to add a parameter to the query.

IDbCommand command = this.NewDbCommand("select * from SomeTable where field = @id");
this.AddDbCommandParameter(command, "@id", "aa");
return this.ExecuteQuery(command);

Template: esp (as in Execute Stored Procedure), and espp (as in Execute Stored Procedure with Parameter)

Usage: same as "eq" and "eqp", but it expands to a call a Stored Procedure instead.

Usage: within a method on a business object class, expands to the line necessary to a get new DB command using Milos (pastes content from the clipboard, such as s SQL statement into the code).

IDbCommand command = this.NewDbCommand("Select * from table");

Usage: within a method on a business object class, expands to the line necessary to add a parameter to a command object.

this.AddDbCommandParameter(command, "@param", "value");

Usage: within a code block, expands to a using block, and all the developer has to do is to type the main name of the business object (such as Customer); the template will take care of properly naming the type and variable with the right casing.

using (CustomerBusinessObject customerBO = CustomerBusinessObject.NewInstance())
{
                    
}

Template: ube (as in Using Business Entity) and unbe (as in Using New Business Entity)

Usage: same as "ubo", except that it will create the using block wrapping a business entity. "ube" expands so that it calls LoadEntity (to load an existing row from the database), whereas "unbe" expands so that it calls NewEntity (to create a brand new row on the database).

Template: nbo (as in New Business Objects), nbe (as in New Business Entity), and lbe (as in Load Business Entity).

Usage: all these templates will declare a variable, name it, and instantiate it, depending on what main name for the class the developer types. NOTE: these templates should only be used in case the objects are not to be disposed by the method creating them. Favor using the "ubo", "ube", "unbe" templates instead, since the using block disposes the object automatically.

CustomerBusinessObject customerBO = CustomerBusinessObject.NewInstance();
CustomerBusinessEntity customerBE = CustomerBusinessEntity.NewEntity();
CustomerBusinessEntity customerBE = CustomerBusinessEntity.LoadEntity(pk);

Usage: expands to a class definition that inherits from the Milos BusinessRule class.

private sealed class CustomerCreditMustBeHighBusinessRule : BusinessRule
{
    public CustomerCreditMustBeHighBusinessRule()
           : base("Customers", RuleViolationType.Violation)
    {
    }

    public override void VerifyRow(DataRow currentRow, int rowIndex)
    {
        this.LogBusinessRuleViolation(currentRow, rowIndex, "Balance", "Credit must be high.");
    }
}

C#, VB, and VS Code Snippets

Right now, our custom templates only support C#; we will work on support for VB as well. We are also considering creating templates using Visual Studio's "Code Snippets" (for those who aren't using CodeRush), but we don't have a timeframe for that yet.

More custom templates?

We are certainly going to create more custom templates as time goes by, and as we do, we'll make it available, and post the updates to this blog so that everybody can be aware of it. If you think of any template that would be really helpful to have, shoot me an email, and I'll see if we can implement it.

As mentioned in the "Top 10 Must Have Features in O/R Mapping Tools" article, inheritance is one of the core concepts in object-oriented programming, and relational databases don't support such concept. Milos Business Objects do support means for that, though. This can happen in two ways:

In fact, Milos has a NameComponents module, which has a set of classes to be used for "names" (or contacts) manipulation (that includes business object, entity, and UI controls). That way, we don't have to recreate that functionality over and over again. We then subclass those business object/entity classes, to extend it into special classes such as Employee, Customer, and anything else that is-a specialized version of a contact in the application.

I'd like to mention that I'm keeping the posts on this series short, since my main focus at this point is to mention whether or not (and a little bit of how) Milos supports those "top 10 must have features"; when we're done with the series, I'll spend some more time into actually posting more details on each of those features. Stay tuned!

Following the series based on this article, this next installment covers how Business Objects module in Milos deals with Relationships and Life Cycle Management. So here we go (again, basing the contents off of the aforementioned article):

For all these scenarios, we have code generator (that runs as a plug-in for Visual Studio) that facilitates a lot the creation of the objects, already configured to be used right away. In a couple of days I'll be posting about a new version of our code generator that's coming out soon.