Phil Gilmore

Using Generics in Delphi

Phil Gilmore — Wed, 23 Dec 2009 22:55:00 GMT

Phil Gilmore

12/23/2009, revised 02/25/2010

Introduction

Generics were introduced in Delphi in version 2009. They were implemented as first class citizens in the Object Pascal language. They work splendidly and support all the features you would expect. This is a huge improvement for this struggling language. If you are in the majority of Delphi users who refuse to move past Delphi 7, you now have plenty of reason to upgrade.

What’s so great about generics?

Once you’ve written a class using generic type parameters (generics), you can use that class with any type and the type you choose to use with any given use of that class replaces the generic types you used when you created the class. The chosen type now appears as your method parameters, return types and property types. You don’t have to cast or convert the types… it’s as if the class was written with that type in mind all along.

For example, most of us have used the TObjectList. You can use it by itself and just stick objects in it and pull them out again. But that requires you to cast the objects from TObject back out to TWhateverMyClassNameIs every time you fetch them. You can also write a descendant class from TObjectList and override the TObject members with your custom type. But then the class only works with your type.

Imagine using a generic TObjectList. TObjectList<TMyCustomType> and its methods accept parameters of type TMyCustomType and its collection yields TMyCustomType objects instead of TObject. And you never have to write code to make it aware of TMyCustomType. That’s what generics can do for you.

This is done by building the class with a placeholder for a runtime type. At runtime, you provide that type to the class when you declare it. Then that type replaces your placeholder throughout the class when you instantiate an object from it.

First look

Syntactically, you’ll initially be surprised how much Delphi generics resemble C# generics. There are few differences and they’re similar enough that you won’t have any trouble switching gears between the two. Let’s look at a generic class.

unit GenericSample1;

interface

type
  TGenericArray<T> = array of T;

type
  TMyData<T> = class(TObject)
  public
    function Add(const aExistingSet: TGenericArray<T>;
      const aNewValue: T): TGenericArray<T>;
  end;

implementation

{ TMyData<T> }

function TMyData<T>.Add(const aExistingSet: TGenericArray<T>;
  const aNewValue: T): TGenericArray<T>;
begin
  { You could append the new 
  value to the existing set and return it here. }
end;

end.

A class can have a type parameter (usually named T when only one parameter is present) as shown above. You can also have a parameterized method like this:

unit ParameterizedMethodExample1;

interface

type
  TMyData<T> = class(TObject)
  public
    procedure ParameterizedMethod<T2>(const aGenericParameter: T2);
  end;

implementation


{ TMyData<T> }

procedure TMyData<T>.ParameterizedMethod<T2>(const aGenericParameter: T2);
begin
  // Do something with T2.
end;

end.

You can have multiple parameters:

unit MultipleParametersExample1;

interface

type
  TMyData<T, T2> = class(TObject)
  public

  end;

implementation


end.

Generic Constraints

Given that the type is unknown, it’s sometimes difficult to do much with a member or parameter of a generic type, because an unknown type has unknown members and the compiler won’t let you assume what those members are. It must know the type.

You can assert some assumptions using generic type constraints. This is where we first deviate from C# syntax. In C#, your constraints are declared at the end of the class or method declaration, prefaced with the where keyword. Here are some C# constraint declarations.

public class MyData<T> where T: class { }

public class MyData<T> where T: class, IMydata { }

public class MyData<T> where T: class, IMydata, new { }

It almost looks a little Pascal-ish, doesn’t it? Instead of a suffix of the declaration, Delphi neatly declares constraints inline as if it were a type, in traditional Pascal fashion. Here are the equivalent Delphi declarations.

unit ConstraintsExample;

interface

type
  IMyInterface = interface ['{78B5F879-BE4A-436A-B4FB-96A5329B3386}']
    function GetText: string;
  end;

type
  TMyConcreteClass = class(TInterfacedObject, IMyInterface)
  public
    function GetText: string;
  end;

type
  TMyData1<T: class> = class(TObject)
  public
    procedure WhatCanItDo(const aParm: T);
  end;
type
  TMyData2<T: TMyConcreteClass, IMyInterface> = class(TObject)
  public
    procedure WhatCanItDo(const aParm: T);
  end;
type
  TMyData3<T: class, IMyInterface, constructor> = class(TObject)
  public
    function WhatCanItDo(const aParm: T): T;
  end;

implementation


{ TMyData1<T> }

procedure TMyData1<T>.WhatCanItDo(const aParm: T);
var
  p: pointer;
  obj: TObject;
begin
  // Here, <T: class> tells us it descends from TObject
  obj := TObject(aParm);

  // We also know that it is a reference type.
  p := Pointer(TObject(aParm));
end;

{ TMyData2<T> }

procedure TMyData2<T>.WhatCanItDo(const aParm: T);
var
  intf: IMyInterface;
  conc: TMyConcreteClass;
begin
  // Here, <T: TMyConcreteClass, IMyInterface>
  // tells us T descends from TMyConcreteClass,
  conc := TMyConcreteClass(aParm);

  // and that T implements IMyInterface.
  intf := TMyConcreteClass(aParm) as IMyInterface;
end;

{ TMyData3<T> }

function TMyData3<T>.WhatCanItDo(const aParm: T): T;
begin
  // Here, <T: class, IMyInterface, constructor> tells us that
  // the T type has a default (parameterless) constructor
  // and we can create an instance of that type.
  // We also know that any instance we create implements
  // the IMyInterface interface.

  result := T.Create;
end;

{ TMyConcreteClass }

function TMyConcreteClass.GetText: string;
begin
  result := 'Sample text.';
end;

end.

In the code above, I show constraints using the class, interface and constructor elements. Constraints may have a base class instead of the class element, indicating that the type must descend from the base class indicated. You may also use the record element to indicate that the type is a value type or record type.

Given the constraints in the examples above, TMyData1 must receive a class for its type parameter. It cannot be a primitive or a record. TMyData2 and TMyData3 must receive a class that is or descends from TMyConcreteClass. Any primitive, record or incompatible class type will generate a compiler error.

Here are example declarations to consume these classes:

var
  data1: TMyData1<TObject>;
  data2: TMyData2<TMyConcreteClass>;
  data3: TMyData3<TMyConcreteClass>;

Here are some declarations that violate our constraints.

var
  mustBeObjectData: TMyData1<TMyRecord>;
  mustBeConcreteType: TMyData2<TObject>;

Here are the errors our violations will raise at compile time.

[DCC Error] Unit1.pas(48): E2511 
Type parameter ‘T’ must be a class type
[DCC Error] Unit1.pas(49): E2515 
Type parameter ‘T’ is not compatible with type ‘TMyConcreateClass’
[DCC Fatal Error] Project1.dpr(6): F2063 
could not compile used unit ‘Unit2.pas’

The first is because we pass a record where the constraint demands a class, and the second is because we pass a TObject where the constraint demands a class the descends from TMyConcreteClass, which TObject does not do.

Multiple parameter syntaxes

When using multiple type parameters, syntax has some strange complications. So far, we’ve looked at the syntax for a single type Parameter.

public
  function Method1<T>: T;

The syntax for multiple parameters is a comma-separated list of type parameters. You can optionally use a semicolon to separate the methods as well.

public
  function Method2<T1, T2>: T2;
  function Method3<T1; T2>: T2;

However, type parameter constraints will throw a wrench into the mix. If you add a constraint to any of the type parameters, the comma is no longer allowed and the semicolon is required.

public
  function Method4<T1: class; T2>: T2;
  function Method5<T1; T2: IInterface>: T2;
  function Method6<T1: class; T2: IInterface>: T2;

There is no difference in the implementation section. A comma-separated list of type parameter names is all that is needed. However, the the parameter names must be complete and correct, and there is currently a bug in Delphi 2010 where code completion does not generate the implementation declarations properly (only the first parameter is included in the method implementation). Here is a proper set of declarations for all the examples above:

function TMyClass.Method1<T>: T; begin end;
function TMyClass.Method2<T1, T2>: T2; begin end;
function TMyClass.Method3<T1, T2>: T2; begin end;
function TMyClass.Method4<T1, T2>: T2; begin end;
function TMyClass.Method5<T1, T2>: T2; begin end;
function TMyClass.Method6<T1, T2>: T2; begin end;

Scope

A type parameter in a class type parameter list is visible anywhere inside that class. It can be used for method parameters, method return values, field types, property types or method local variables.

A method can also have a generic type parameter list and those parameter lists also support constraints. A type parameter in a method type parameter list is visible anywhere inside that method.

Here is a unit which demonstrates various generic parameter scopes.

unit ScopeExample;

interface
uses Classes;

type
  TScopeExample<T: class> = class(TObject)
  public
    fGenericField: T;
    function GenericMethod<T2: TStringList>(const aParameter1: T; const aParameter2: T2): T2;
    procedure UsedAsParameterType(const aParameter: T);
    function UsedAsMethodReturnType: T;
    property UsedAsPropertyType: T
      read UsedAsMethodReturnType
      write UsedAsParameterType;
  end;

implementation

{ TScopeExample<T> }

function TScopeExample<T>.GenericMethod<T2>(const aParameter1: T;
  const aParameter2: T2): T2;
begin
  if (T.ClassInfo = TStringList.ClassInfo) then
    result := T2(aParameter1)
  else
    result := aParameter2;
end;

function TScopeExample<T>.UsedAsMethodReturnType: T;
var
  lUsedAsLocalVariable: T;
begin
  result := lUsedAsLocalVariable;
end;

procedure TScopeExample<T>.UsedAsParameterType(const aParameter: T);
var
  lUsedAsLocalVariable: T;
begin
  lUsedAsLocalVariable := aParameter;
end;

end.

Generics in VCL

There is a concept of self-obsolescence behind generics. Because you now have generics, you may quickly go through your previous patterns and adopt them to use generics. But once they’re done, you find that they’re so reusable that you need not write any code to accommodate your most common patterns anymore after that. Well, there’s more news. Be it good or bad, The VCL has implemented many of those patterns using generics. So you may not need to make those conversions in the first place. Let’s explorer some of the generic structures and classes that the VCL now provides.

While generic declarations are now lightly sprinkled throughout the VCL, the starting point for most generics support is implemented in three basic units.

uses
SysUtils,
Generics.Defaults,
Generics.Collections;

In general, support for iterators and comparers are declared in Generics.Defaults, and collection structures are declared in Generics.Collections.

Here are the public declarations in Generics.Defaults.pas:

Classes / Interfaces	Description
IComparer<T>	Implements a compare function returning less-than, greater-than or equal-to.
IEqualityComparer<T>	Implements a compare function returning equal-to or not.
TComparer<T>	Abstract class for implementing IComparer<T>.
TEqualityComparer<T>	Abstract class for implementing IEqualityComparer<T>
TSingletonImplementation	Weak-reference implementation of TInterfacedObject. Instances are not automatically freed.
TDelegatedEqualityComparer<T>	A comparer that takes a delegated comparison function and uses it to determine equality.
TDelegatedComparer<T>	A comparer that takes a delegated function to do the actual comparison.
TCustomComparer<T>	An abstract singleton class for comparison operations.
TStringComparer	Compares strings.
Method prototypes / delegates
TComparison<T>	A delegate method prototype for less-than, greater-than, or equal-to comparisons.
TEqualityComparison<T>	A delegate method prototype for equality comparisons.
THasher<T>	A delegate method prototype for getting the hash value of an object or value.
Concrete Functions
function BobJenkinsHash(const Data; Len, InitData: Integer): Integer;	Returns a hash from the given data.
function BinaryCompare(const Left, Right: Pointer; Size: Integer): Integer;	A method to compare binary data. Does not match comparison prototypes, so must be used from a comparison class rather than pass as a delegated method.

Here are the public declarations in Generics.Collections.pas:

Classes / Interfaces	Description
TArray	Contains no data, but provides methods for working with arrays. Strangely, the class is not generic and the members are. This can easily be confused with TArray<T>, which is in System.pas, which contains data and no methods.
TEnumerator<T>	Implements the iterator pattern on your data.
TEnumerable<T>	Returns an enumerator, allowing your class to be used in a For..In construct.
TList<T>	A generic collection or objects, records or primitives.
TQueue<T>	A generic queue (first in / last out) collection.
TStack<T>	A generic stack (first in / first out) collection.
TPair<TKey, TValue>	A structure containing two child members of disparate types.
TDictionary<TKey, TValue>	A searchable collection with lookup keys.
TObjectList<T: class>	A generic collection of objects (records and primitives not allowed).
TObjectQueue<T: class>	A generic queue of objects.
TObjectStack<T: class>	A generic stack of objects.
TObjectDictionary<TKey, TValue>	A generic collection of owned objects with lookup keys.
Enums
TCollectionNotification	Used in TCollectionNotifyEvent<>
TDictionaryOwnerships	Used by TObjectDictionary<>
Method prototypes / delegates
TCollectionNotifyEvent<T>	Used by various collections to implement an observer pattern.
Concrete functions
InCircularRange
Type aliases
PObject	Pointer to TObject.
Exceptions
ENotsupportedException

Here are the pertinent declarations in SysUtils.pas:

Method prototypes / delegates	Description
TProc	A procedure with no parameters.
TProc<T>	A procedure with one generic parameter.
TProc<T1, T2>	A procedure with two generic parameters.
TProc<T1, T2, T3>	A procedure with three generic parameters.
TProc<T1, T2, T3, T4>	A procedure with four generic parameters.
TFunc<TResult>	A function with no parameters and a generic return type.
TFunc<T, TResult>	A function with one generic parameter and a generic return type.
TFunc<T1, T2, TResult>	A function with two generic parameters and a generic return type.
TFunc<T1, T2, T3, TResult>	A function with three generic parameters and a generic return type.
TFunc<T1, T2, T3, T4, TResult>	A function with four generic parameters and a generic return type.
TPredicate<T>	A function with one generic parameter and a boolean return type. This is used by collections as a “filter” for elements. Elements that are passed to a predicate function which return false are excluded from the result.

The delegate types in SysUtils are interesting if you know how they are used. They are probably just going in one ear and out the other if you don’t. These delegates are often the prototypes for anonymous methods. These are methods that can be declared in place and passed as parameters to other methods, but they are not pointers to methods of another object or class (although they can be). You can create your own methods that take one of these types as a parameter, call that method and do something with the result. This is a means of passing some control back to the caller, as they provide the code you’re calling. I expected these function prototypes to be used as predicates on many of the new generic collection types… but I find that there are not used anywhere. This is strange, but for now, it simplifies our discussion. You will not need to know anything about the declarations in SysUtils.pas to use generics in Delphi.

What is Covariance and Contravariance?

Covariance is the ability to implicitly convert a value from a more specific type to an ancestor type.

Contravariance is the ability to implicitly convert a value from a less specific type to a derived type.

Generic Covariance and Contravariance

It is often disappointing to a user who begins using generics to find that covariance and contravariance is not supported in their implementation. They are not supported in Delphi for native Windows. Interestingly, they are supported in Prism on the .NET 3.5 framework although they aren’t available in C# until version 3.0 comes out on the .NET 4.0 platform.

At first it would seem that a method with a parameter of type TList<TStrings> could accept a value of type TList<TStringlist>. Because TList is compatible with TList and TStrings is an ancestor of TStringList, it would seem that TList<TStringList> derives from TList<TStrings> but it doesn’t. The type system is actually comparing TList<T1> to TList<T2>, which are incompatible types.

The expression TList<T> is not to be thought of as a composition of 2 types with two sets of type information to be compared to another two sets of type information when determining compatibility. TList<T> is a single type with a single set of type information. Hence, compatibility between T1 and T2 is not applicable… To make such type comparisons would require covariance and contravariance.

Generics in older versions of Delphi (Templates)

Generics were introduced in Delphi 2009. However, with some effort, you can achieve something similar in older versions. Delphi can be tricked into building a sort of untyped template with some compromise in readability.

The article titled “Templates in Object Pascal” by Rossen Assenov describes how to do this. The article can currently be found here.

http://edn.embarcadero.com/article/27603

Basically, you write your template in two parts, an interface and an implementation. Then in the consuming unit, you declare a type alias for your “type parameter” (the type placeholder you put in your template) and then immediately add an include directive for the interface snippet. In the implementation section you add an include directive for the implementation snippet to finish it up. This has the limitation that the template can only be consumed once per unit, but that’s a small price to pay for some of the benefits you might reap.

Phil Gilmore (www.interactiveasp.net)

Getting started with MyGeneration, a primer and tutorial

Phil Gilmore — Fri, 04 Dec 2009 00:36:00 GMT

12/03/2009

Phil Gilmore

About MyGeneration

MyGeneration is a developer's code-generation tool that gives you access to your database’s schema. It is useful for building O/RM entity classes based on your database schema.

MyGeneration is mature, free and open-source. It supports many databases. It supports scripting in many languages (C# script VB.NET script, jscript, vbscript, etc.). It supports output into any language. You can write your own templates or use someone else’s.

There are many templates available. Some come with the installer, but many more can be browsed and downloaded from the internet right in the MyGeneration main window.

I found it easy enough to get started using someone else's downloadable templates, so I will only take a brief moment to describe that. I will then spend more time explaining how to write your own templates.

The MyGeneration main page is here and has the latest download link to download.com.

http://www.mygenerationsoftware.com/portal/default.aspx

As the this writing, the download link points here. This download is an NSIS installer package. I recommend installing all components.

When you first run MyGeneration, you are presented with the Default Settings screen. The purpose of this window is to give you a place to define your database connection.

Using the OLEDB configuration wizard (1, see image below), you can easily produce a working connection string. You can also get a generic one here to get your started if you have trouble. Or, enter the string manually if you have the aptitude for it. However you do it, the point is to get the connection string into the connection string field (2).

Once you test your connection string (3) and can connect, type a name for your connection in the box above (4) and save it (5). Now you can always refer to this connection string by selecting it in the dropdown list (4) and clicking the load button. Set the language mapping to your preference (i.e. C#). The other settings are usually left as default. Click the Save button at the top of the page and you may continue.

MyMeta

The MyMeta library is the body that fetches metadata from your database engine. It’s the part that must be aware of your particular database engine in order to support it. You can see what MyMeta can see by opening the MyMeta browser window and viewing its tree contents. If you don’t see your database schema in the MyMeta browser, your connection isn’t set up correctly or you don’t have permissions to see the things you’re looking for. In any case, the data won’t be accessible for code generation unless it is visible in the MyMeta browser.

Templates

There are two ways to do code generation in MyGeneration. The first is to use someone else’s template. The second is to write your own. Most folks who are using a mainstream O/RM such as NHibernate and a mainstream language such as C# can pick a template that works with both and be done in a few minutes. Others can write some templates in a few hours for any systems they want to use, as long as MyMeta supports their database engine.

Using someone else’s templates

In case you want to just get some code generation done and be done with this, I’ve put this here so you don’t have to wade through the rest of this document to get your work done.

MyGeneration’s installer will give you a handful of templates that you can use. These are limited and probably don’t have what you want.

One of the nice things about MyGeneration is that you can browser for more templates online without leaving the application. Click the globe icon in the template browser to find more templates online…

Now we’re talking! You now have the latest templates. It isn’t always easy to find what you’re looking for, but usually they’re categorized pretty well. You may look for a template by the language you want to generate, or you may search by the database engine or data access framework you’re using, such as NHibernate.

Double-click a template to see some pretty good detail about it if you need to know more about it. When you’ve found a template you like, click the save button and continue for more templates or close the Online Template Library window when you’re done.

The templates you saved will now appear in your regular Template Browser. You can right-click on the desired template in the Template Browser, click EXECUTE from the popup menu, and code generation will begin.

What happens at that point depends on the template. Many templates will need you to give them some input parameters to do their job. When this is the case, they will prompt you for parameters with their own popup form. When it is complete, you will have output in the output window, or the output will be saved to a set of files. This is also specific to the template. Most templates that output to files will prompt you for an output location.

Modifying someone else’s template

If you followed the steps above in “Using someone else’s templates”, you know how to get your hands on a template that you can modify. Take any template in your template browser and double-click it. The template can be modified right inside the MyGeneration application. If you’re modifying someone else’s template, I cannot give you very specific direction. From here on, I will only give direction about how to create a new template.

Creating your own template

Relax. This really is easy. You can pick from several languages and probably won’t have to learn a new language to do this. There is code insight, useful error messages and bugs are easy to fix.

Here some more information about MyGeneration that you will need to know. First, MyGeneration has several systems. We’ve already covered MyMeta, MyMeta Browser, Template Browser, and Online Template Browser. There are separate help files for different systems too. This is useful to know because you will be using these help files from time to time. The help files really have good information, but it can be hard to find what you’re looking for, especially if you don’t know which help file to look in.

The systems you’re primarily concerned with are Zeus, and MyMeta. Unless you are using any of the other systems listed under Help.

Zeus is the scripting engine that MyGeneration uses. It is the engine that takes your templates, executes them to create a program for code generation and then executes that code generation program and either passes the output back to MyGeneration or outputs it to a file (if the script tells it to). Zeus can use several languages. It supports C# Script, VB.Net Script, VBScript and JScript. I will proceed under the assumption that you are using C# Script.

MyMeta, as we have discussed, is a set of objects that your Zeus script can ask for when it needs information about your database schema. There are many object types in this library and you will probably want to just browse over the help file for it to familiarize yourself with some of the interfaces that you will be using. They are mostly self-evident.

The Zeus engine has an output object that to which the generated code will be written. This output would be sent to the Output window by default. However, many templates will redirect this output to a file. If that happens, the output may not appear in the output window.

The Zeus engine has an input object that can be queried for parameters that the user enters are runtime. Runtime is the time at which the Zeus script is executed. Using the input object is optional.

To create a new template, click File, then New –> C# Zeus Template. The template will appear in a new tab on the main MyGeneration panel. Inside that “Untitled” panel are 4 more tabs.

Tab	Description
Template Code	You write this script. This script builds the Template Source script.
Interface Code	You write this script. It builds a UI for gathering parameters from the user.
Template Source	This script is generated and you do not touch it. This is the code generation program. This is the output of the Template Code script. Look here if you have errors if your Template Code script.
Interface Source	This script is generated and you do not touch it. As the TemplateCode generates the Template Source, so too does the Interface Code generate the Interface Source. Use this to debug your Interface Code.
Output	If the output from the Template Source is not redirected to a file, you will see it here when you execute the template.

As you can see, you will do your editing primarily in the template code tab. If you build a UI, you will also use the interface code tab.

In its simplest form, a template can be comprised simply of template code which accesses the MyMeta object as input and the output object as output. Next, you will want to redirect output to files, then finally build a UI. The data gathered in the UI is made available to the template code via the input object.

Let’s start with something simple. In the Template Code and Interface Code tabs, you will see some default code. Keep it. You will need it. Run the template (F5). You see the output in the output tab. Great! Back at the Template Code window, find the Render() method. This is where you will write your code. It is your entry point. You can write your own methods outside of it and call them from the Render method.

Server tags

<% and %> tags define blocks of code within the Template Code. As in ASP or JSP, this is technically a code file, but anything outside the server tags is output as a literal. Note that in the Template Code window, there is literal region that looks like this:

        %>        
You can toggle in and out of script like this         
<%

Take a look at the Template Source tab. You’ll see that this literal has been converted to this:

output.writeln("You can toggle in out of script like this");

To keep things simple for now, I removed indentation of this literal in the template code window. You will find that line breaks and tabs will be adhered to in these literal regions. For finer control, you can use direct output in the Template Code like this:

        output.writeln("You can toggle in out of script like this");        
%>         
You can toggle in out of script like this         
<%

The output becomes:

        output.writeln("You can toggle in out of script like this");        
output.writeln("");         
output.writeln("You can toggle in out of script like this");

Of course, if you only did your literal output in this way, your template code would be identical to your template source. But until you get used to it, you can do this to fine tune your whitespace.

You can also dereference a single symbol from your code without using a call to output.writeln() using the <%= %> tags. For example:

        int keyCount = input.Keys.Count;        
int j = 0;         
foreach (string inputKey in input.Keys)         
{         
    j++;         
    string inputValue = input[inputKey].ToString();         
    %>Input key <%=j.ToString()%><%         
    %> of <%=keyCount.ToString()%><%         
    %>: <%=inputKey%><%         
    %> = <%=inputValue%><%="\r\n"%><%         
}

The Dereference Symbol tag pair is equivalent to the output.writeln. Notice that you never put a semicolon between these tags. To do so would generate something like this in the Template Source. So this tag:

        <%=j.ToString();%>

Would generate this:

        output.write(j.ToString(););

While it’s obvious to see how the premature semicolon breaks the generated code, it is still sometimes hard to remember to omit your trailing semicolons when using the Dererence Symbol tags. Understanding that the text is output verbatim to an output.writeln() call makes it easier to keep things straight.

Using MyMeta

Okay, so we could output anything we want now, but we don’t have much to do without some input. The input is going to start from our database schema. This comes from the MyMeta object. MyMeta is a global object instance of the MyMeta library and is available throughout your script. Have a look at what it can do…

The databases property will give you a collection of databases. From there, you can drill down into tables, columns, keys, stored procedures, etc. To get a single database, first you have to access it by index from the MyMeta.Databases collection.

MyMeta.Databases["Northwind"]

Type the line above in the Render method. This references the Northwind database. For RDBMS servers like Oracle, there may be one or many databases. For local databases, this may not apply.

Now that we are referencing a database, you should be able to reference schema information for the tables on that database. You can drill down from the database reference to its tables collection. But lo, press the period key at the end of that line, and no code insight comes up. The code insight is useful but limited. It does not show you types, and sometimes it doesn’t know the type of the subject and can’t show its members.

Workaround – If you assign that reference to a strongly typed variable, the variable gives the code insight enough information to show you its members. There’s just one problem. You don’t know the type either. You’ll have to guess. This sounds terrible, but it’s not that bad. Remember I said you need to be familiar with the help files? Open the MyMeta help file from the MyGeneration help menu.

Right there in the root you can see a list of interfaces provided by MyMeta. You can easily guess which type our reference is. It is an IDatabase.

Now we have the next level of code insight. This is only required for code insight. Instead of this (which provides code insight):

        IDatabase db = MyMeta.Databases["Northwind"];        
ITable tbl = db.Tables["table1"];         
IColumn col = tbl.Columns["id"];         
output.writeln(col.Name);

This would work too. But you have to be more familiar with MyMeta object hierarchies.

        output.writeln(        
    MyMeta         
        .Databases["Northwind"]         
        .Tables["table1"]         
        .Columns["id"].Name         
);

Most collections in MyMeta have named members and can be accessed by ordinal index or by named index:

        MyMeta.Databases[0];        
MyMeta.Databases[“Northwind”];

You now have all the tools you need to build and run a useful code generation template using MyGeneration.

Redirecting output

Expect to be executing your templates repeatedly during development of the template itself and periodically during development of whatever project consumes your generated code. It becomes cumbersome to copy the contents of the output window from the clipboard (MyGeneration automatically copies it to the clipboard when it writes to the output window) over to an editor to overwrite previous output. It would be convenient to write output directly to a file on disk. The output object can do this. It can also write to multiple files.

For more detail on the output object, see the Zeus help files under IZeusOutput and ZeusOutput class. But here is a basic use of output to files.

        // At first, our output buffer is empty.  Add something to it.        
output.writeln(“Something”);         
        
// Save the current buffer to 2 different files.         
output.save(path1, “o”);         
output.save(path2, “o”);         
        
// Start a new buffer and save it to a third file.         
output.clear();         
%>Something else<%         
output.save(path3, “o”);         
        
// Start a new buffer and since we don’t clear it, it shows up in the output window.         
output.clear();         
%>Wrote to: <%=path1%><%         
%>Wrote to: <%=path2%><%         
%>Wrote to: <%=path3%><%

You may have noticed that I’m mixing %>literals<% (outside the server code) with explicit writeln.output() calls. Remember that these are interchangable and you’ll want to shoot for consistency most of the time. I just mixed them up to show some variety in my examples.

The second parameter of the save() method (“o”) is not documented under IZeusOutput very well. They are found under the ZeusOutput class, but poorly. I’ll document them here to save you time.

Value	Description
“o”	Overwrites an existing file.
“b”	Overwrites existing file but backs it up first.
“a”	Appends an existing file.
“d”	Do not overwrite (silent failure).

Building a UI for your template.

If you need parameters for your template execution they can be gathered at runtime by a UI which you build into your template. The UI code is written in the editor under the Interface Code tab. Again, the default sample code should be kept to get you started. The Setup() method is your entry point. In here, you have a global object named ui. It is of type Zeus.UserInterface.GuiController. You will find help for it in Zeus help under Zeus.UserInterface.

In a nutshell, you have some Addxxxx methods to create UI elements such as buttons and comboboxes. These methods return objects of the corresponding type (IGuidButton, etc.). Those objects then have layout properties such as top, bottom, width, etc. To keep things simple, the IGuiController ui is very good as choosing default layout parameters for you. if you add an element to the UI, it will appear in vertical order relative to other elements you have added. It will fill the form horizontally. While this isn’t always pretty, it makes it easy to get started.

First thing’s first. The interface is disabled for now. Uncomment the contents of the Setup() method to see what happens.

        public override void Setup()        
{         
  ui.Width  = 100;         
  ui.Height = 100;         
  GuiLabel lblDemo = ui.AddLabel("lblDemo", "Demo", "Demo Tooltip");         
  ui.ShowGui = true;         
}

That wasn’t hard. The code sizes the form (lines 1 and 2), adds a label (line 3) and displays the form (line4). To expound on this, we’ll keep lines 1, 2, and 4. We’ll increase the size of the form and replace line 3 with our customized form code.

        public override void Setup()        
{         
  ui.Width  = 500;         
  ui.Height = 300;         
   
  // Customize things here...         
   
  ui.ShowGui = true;         
}

Next we’ll add some controls that are actually going to be useful in this sort of project. We’ll add a database selection combo box and an output file selector (with labels). I’ll add them to their own method to keep the Setup() method cleaner. Remember that the ui object creates the controls for us. This is a bit easier than MyMeta. These functions have code insight that tells us the return type.

Easy enough? This won’t take long.

        public void CreateControls()        
{         
  // Database selection drop-down.         
  GuiLabel lblSelectDatabase =         
   ui.AddLabel("lblSelectDatabase", "Select a database:", "");         
  GuiComboBox cboSelectDatabase =         
   ui.AddComboBox("cboSelectDatabase", "Select a database");         
    
  // Output file picker         
  GuiLabel lblOutputFile =         
   ui.AddLabel("lblOutputFile", "Output filename: ", "");         
  GuiTextBox txtOutputFile =         
   ui.AddTextBox("txtOutputFile", "", "Output filename");         
  GuiFilePicker fpOutputFile =         
   ui.AddFilePicker("fpOutputFile", "...", "", "txtOutputFile", false);         
}

Notice that when passing a control as a parameter to an Addxxx() method, it expects the control name as a string, not the object reference for that control. To keep things straight, I always make the string ID parameter which I pass to the add method identical to the object reference to which I assign the ui element (lblOutputfile = ui.AddLabel(“lblOutputFile”…) for example).

Well, that creates the form controls, but they have no data behind them. You will frequently need to bind MyMeta elements to your UI elements. We will want to do so with our database selection combo box.

        cboSelectDatabase.BindData(MyMeta.Databases);

How easy was that? The layout is still a little ugly, but we now have a working UI. The next step is to use it from the Template Code. We’ll get to that in a moment.

UI Layout

Right now, let’s fix up the layout a bit for sanity’s sake. This is easy too. Just set the width, height, top and left properties of each UI element. You can calculate them in conjunction with the width and height properties of the ui object.

Here is the finished UI. As simple as it is, it may be all you need for some projects.

        public class GeneratedGui : DotNetScriptGui        
{         
    // Declare UI elements in class scope.         
    GuiLabel lblSelectDatabase;         
    GuiComboBox cboSelectDatabase;         
    GuiLabel lblOutputFile;         
    GuiTextBox txtOutputFile;         
    GuiFilePicker fpOutputFile; 
          public GeneratedGui(ZeusContext context) : base(context) {} 
          //-----------------------------------------        
    // The User Interface Entry Point         
    //-----------------------------------------         
    public override void Setup()         
    {         
        ui.Width  = 500;         
        ui.Height = 300;         
        ui.Title = "Building our first UI!";         
        // Customize things here...         
        CreateControls();         
        LayoutControls();         
        DataBindControls();         
        ui.ShowGui = true;         
    } 
          public void CreateControls()        
    {         
        // Database selection drop-down.         
        lblSelectDatabase =         
            ui.AddLabel("lblSelectDatabase", "Select a database:", "");         
        cboSelectDatabase =         
            ui.AddComboBox("cboSelectDatabase", "Select a database"); 
              // Output file picker        
        lblOutputFile =         
            ui.AddLabel("lblOutputFile", "Output filename: ", "");         
        txtOutputFile =         
            ui.AddTextBox("txtOutputFile", "", "Output filename");         
        fpOutputFile =         
            ui.AddFilePicker("fpOutputFile", "...", "", "txtOutputFile", false);         
    }         
    public void LayoutControls()         
    {         
        // Form         
        ui.Width  = 500;         
        ui.Height = 150;         
        ui.Title = "Building our first UI!";         
        int margin = 12;         
        // Position dropdown and label.         
        lblSelectDatabase.Width = 100;         
        lblSelectDatabase.Left = margin;         
        lblSelectDatabase.Top = margin;         
        cboSelectDatabase.Width = ui.Width         
            - lblSelectDatabase.Width - margin * 3;         
        cboSelectDatabase.Top = lblSelectDatabase.Top;         
        cboSelectDatabase.Left = lblSelectDatabase.Left         
            + lblSelectDatabase.Width + margin ;
              // Position file picker        
        lblOutputFile.Width = lblSelectDatabase.Width;         
        lblOutputFile.Left = lblSelectDatabase.Left;         
        lblOutputFile.Top = lblSelectDatabase.Top         
            + lblSelectDatabase.Height + margin;         
        fpOutputFile.Width = 25;         
        fpOutputFile.Top = lblOutputFile.Top;         
        fpOutputFile.Left = ui.Width - fpOutputFile.Width - margin;         
        txtOutputFile.Width = ui.Width         
            - fpOutputFile.Width - lblOutputFile.Width - margin * 4;         
        txtOutputFile.Top = lblOutputFile.Top;         
        txtOutputFile.Left = cboSelectDatabase.Left;         
    } 
          public void DataBindControls()        
    {         
        cboSelectDatabase.BindData(MyMeta.Databases);         
    }         
}

Consuming the UI, Method 1: Input

You have a working UI now but what good is it? What does it actually do? By itself, it lets you specify parameters but those parameters have to be consume by the Template Code script. It does so in two ways. I’ve mentioned before that the first way is through the input object. The input object is also a global instance. Once again, see the Zeus help file under IZeusInput and ZeusInput. The input

object provides the values for the UI elements as selected by the user at runtime. It is more convenient than the second method, which is to access the elements themselves. It is more convenient because every element has a single scalar value. For example, a dropdown list has a list of elements, a selected value, a selected index, etc. The input object contains a single string for that control, the selected value.

The input object is a collection of values, each with a name corresponding to a control on the UI form (more specifically the string ID property used in the construction of said control) and a value as entered or selected in that control at runtime. Objects retrieved from this collection must be cast to specific types, usually string.

Here’s an interesting exercise. Put this code in your Template Code’s Render method. It will output all the items in the input collection. Now you’ll know exactly what’s available to you. You’ll see the elements from your UI as well as several fields defined by MyGeneration. MyGeneration input key names begin with double underscores.

          output.writeln("Input fields: ");        
  foreach(string s in input.Keys)         
  {         
   output.write(s);         
   try         
   {         
    output.write("=");         
    output.write((string)input);         
   }         
   catch { }         
    
   output.writeln("");         
  }

You’ll also see an entry for cboSelectDatabase. It is as you selected in the UI. You can now use this in your template code like this:

        IDatabase selectedDB =        
    MyMeta.Databases[(string)input["cboSelectDatabase"]];         
output.writeln("Selected database: " + selectedDB.Name);         
output.writeln(""); 
      foreach (ITable t in selectedDB.Tables)        
{         
    output.writeln("\tTable: " + t.Name);         
    foreach(IColumn c in t.Columns)         
    {         
        output.write("\t\tColumn: name=" + c.Name);         
        output.write(", dbTargetType=" + c.DbTargetType);         
        output.write(", DataType=" + c.DataType);         
        output.write(", DataTypeName=" + c.DataTypeName);         
        output.writeln("");         
    }         
    output.writeln("");         
}

That script will output basic schema for all tables in your database.

Notice that when retrieving the value of the cboSelectDatabase combo box, we did not have to drill into a SelectedValue property to get the selected value. The input object gives us a single string for cboSelectDatabase when we pass its name as a key. The string is its selected value.

Consuming the UI, Method 2: UI

The second method is discouraged. You can use the ui object to retrieve the UI elements directly and query their properties for the values you want.

In the previous example, we might have changed this line:

        IDatabase selectedDB =        
    MyMeta.Databases[(string)input["cboSelectDatabase"]];

and made it work like this:

        IDatabase selectedDB =        
    MyMeta.Databases[((GuiComboBox)ui["cboSelectDatabase"]).SelectedValue];

When I change that line, the rest of the template code still works.

I hope this has given you everything you need to get started. It certainly won’t cover everything you need to learn to achieve your particular task, but my goal was to get you started so that you would know where to look and have the tools to troubleshoot your work. If I’ve left out something fundamental, please let me know.

Phil Gilmore (www.interactiveasp.net)

CodeRush Xpress for Visual Studio 2008 version 3.2.1 cheat sheet

Phil Gilmore — Fri, 19 Jun 2009 18:37:52 GMT

06/18/2009, Phil Gilmore

I've been a CodeRush fan since I bought my first copy from Eagle Software for Delphi many years ago. I recently downloaded CodeRush Xpress for Visual Studio 2008, version 3.2.1. I have constructed a cheat sheet for it which is available for download on this server. In addition to publishing the cheat sheet, I thought I'd write a small review of the product.

I'm busy these days so I didn't get a chance to get cozy with it right away. That's a point I want to make. I installed it but was able to work with it present but without it causing me any problems. Most other add-in packages require immediate attention just to tone down the overbearing features that don't work the way you want them to and hinder your productivity. CodeRush Xpress did not do that. In fact, I didn't find a place where CRXP could be configured at all. I had to go to the help file to figure out how to use it. This wasn't inconvenient, but the fact that it didn't clutter up my Visual Studio menu was a pleasant surprise.

The help file was very well constructed. Everything was grouped intuitively, every topic was covered, easy to find, easy to browse, and very succinct. "To do this, press these keys, this is what you'll see" is the flow. And every feature where applicable has a screen shot. Very nice. A+ on the documentation.

After reading the help file, I knew I would need to build a cheat sheet to remember all the hot keys, as most of the features are hot-key driven. Many are available in the context menu, but I'm a keyboard guy anyway.

So I've created the cheat sheet and was further surprised by how often I was using these features. CRXP is the free version with fewer features than its commercial sibling, but very functional, aesthetically impressive and with unprecedented usefulness.

I do have one small complaint about the product. It creates a lot of files for itself in the source folder for each of your products. You can safely delete them, but they sure clutter up your source control tools. They appear to be cache files (among other things) so it's probably best to leave them where they lie if possible. I'm using Subversion, so I can easily add an Ignore flag on the root folder and the problem is solved. Other systems may not be so tolerant. These files seem to be project specific, so there may not be a better alternative.

Here is a screen shot of the pocket reference cheat sheet. The standard cheat sheet contains additional comments about each feature and is larger. Both fit on a single printed letter-size page (the pocket reference can printed and be trimmed to just over a quarter of a letter-size page).

With that, I leave you with a recommendation that you download, install, learn and use the product, and a short wish list for the talented folks at Developer Express:

Remove DX* files when issuing a CLEAN SOLUTION operation.
Regular expression support in the class nav and file nav dialogs, especially ^ and $ anchors.
The quicknav has a popup tooltip window with details about the item under the mouse cursor. I'm a keyboard guy. It would be nice if the arrow keys could invoke this tooltip window as well.
Drop marker. I was very disappointed to see that this feature was withheld in the Xpress edition.
A "Clear All Markers" feature. I often hit escape too many times while clearing intellisense windows and find myself jumping around unexpectedly through the code to page markers I didn't know were there (dropped by the file nav feature).
An "About" dialog (or node in the options tree) to tell me which version I have installed.
Update the documents to tell me about the configuration dialogs!
More granular breaking points in Increase and Decrease Selection. For example, I should always be able to click on a symbol, increase selection and highlight just that symbol. If that symbol is a method parameter, selection immediately includes the entire parameter declaration, including the type. It does not select Just the current symbol.

Addendum: I have revised my wish list somewhat. I had not discovered that the context menu in the QuickNav and FileNav dialogs had a link to open the Options window. Here, you can configure many things, including markers and shortcut keys. Since then, I have removed the configurable shortcut keys feature request.

You can download CodeRush Xpress 3.2.1 for Visual Studio 2008 here:

http://msdn.microsoft.com/en-us/vcsharp/dd218053.aspx

You can download my CodeRush Xpress 3.2.1 cheat sheets here:

http://interactiveasp.net/media/p/944.aspx

How to support file uploads in ASP.Net MVC

Phil Gilmore — Wed, 03 Jun 2009 22:57:37 GMT

06/03/2009, Phil Gilmore

ASP.NET MVC can support file uploads. You need two components to support file uploads.

A form in your markup (view) which contains an <input type="file"...> tag and which has the proper enctype attribute.
A controller action which will receive the upload information and perform a task with it.

Your form can be as simple as this:

<form action="/MyController/SendFile" enctype="multipart/form-data" method="post">
    <input type="file" id="SourceFile" name="SourceFile" />
    <br />
    <input type="submit" value="Send" name="btnUpload" id="Submit1" />
</form>

Notice the enctype attribute on the <form...> tag. This is required to support file uploads. Notice too that the action points to our controller action which knows how to work with the uploaded file. Lastly, you'll see the <input type="file...> tag inside the form.

Here is a screen shot of the form, rendered in Firefox 3.0.

The form as shown above contains only Html and is fairly universal regardless of the web framework you are using. This means it should be familiar to you. You have probably seen the enctype attribute on a form with its accompanying. The id attribute of the <input type="file"... > tag will be mapped by the MVC framework to a property of your model or to a parameter in the action method (in this case the SendFile action). Here is an example of an action which takes the file as a parameter.

public ContentResult SendFile(HttpPostedFileBase SourceFile)
{

}

This action gets an HttpPostedFileBase object containing properties for the original local filename and the content of the file itself. Notice that the MVC framework only maps this parameter to the file data if the parameter name (SourceFile) matches the id and name parameters from the <input type="file"...> tag in the form.

If you have a strange circumstance which prohibits you from organizing your form and action in this way and MVC cannot map the file data to an HttpPostedFileBase parameter, you can retrieve it manually from the Request object.

public ContentResult SendFile()
{
    HttpPostedFileBase SourceFile = Request.Files[0];
    //...
}

Here is an evaluation of the HttpPostedFileBase object as provided to the SendFile action method.

Once you have an HttpPostedFileBase object, you can work with the file data. Here are the members of the HttpPostedFileBase class.

protected HttpPostedFileBase();
public virtual int ContentLength { get; }
public virtual string ContentType { get; }
public virtual string FileName { get; }
public virtual Stream InputStream { get; }
public virtual void SaveAs(string filename);

This is pretty simple stuff. You can save the file, read the file or get the file's name and mime type (ContentType). ContentLength is generally not necessary since the InputStream already contains the data of the correct size.

Here is a working action that displays the content of any file uploaded to it.

public ContentResult SendFile()
{
    if (Request.Files.Count == 0)
        return new ContentResult() { ContentType = "text/plain", Content = "File upload failed." };
    else
    {
        HttpPostedFileBase SourceFile = Request.Files[0];
        ContentResult result = new ContentResult();
        result.ContentType = "text/plain";

        StreamReader reader = new StreamReader(SourceFile.InputStream);
        string content = reader.ReadToEnd();
        result.Content = content;

        return result;
    }
}

This method doesn't use the MVC-mapped HttpPostedFileBase parameter. This is not as elegant, but doesn't require a matching name or id on the file upload element in the form markup. This may be useful in some cases.

Lastly, entering that <input type="file"...> markup into the form can be error-prone. While the element is not large or hard to read, it must be exact and is inconsistent with styles supporting strongly-typed views mapped to an MVC model. Therefore it may be prudent to extend the HtmlHelper class to make this easier, cleaner and more consistent. I have written an extension method to do this. It has 2 overloads.

public static string Upload(this HtmlHelper helper, string name)
{
    string result = string.Format("<input type=\"file\" id=\"{0}\" name=\"{0}\" />", name);
    return result;
}

public static string Upload(this HtmlHelper helper, string name, object htmlAttributes)
{
    string attributes;
    if (htmlAttributes is IEnumerable<KeyValuePair<string, object>>)
        attributes = (htmlAttributes as IEnumerable<KeyValuePair<string, object>>).ToAttributeString();
    else
        attributes = (new RouteValueDictionary(htmlAttributes)).ToAttributeString();

    string result = string.Format("<input type=\"file\" name=\"{0}\" {1} />", name, attributes);
    return result;
}

Using this extension, my markup can be changed to this:

<% using (Html.BeginForm("SendFile", "MyController", FormMethod.Post, new { id = "sendFileForm", enctype = "multipart/form-data" }))

{ %>

    <%= Html.Upload("SourceFile", new { style="width: 300px;" })%>

    <br />

    <input type="submit" value="Send" name="btnUpload" id="Submit1" />

<% } %>

Personally, I don't think this is as pretty as straight HTML, but it's easier to write consistently, and if you're using MVC, your whole page probably looks like this already anyway. It's your choice. Either way you build the markup, the controller action is unaffected.

None of this is very complicated but I recently had to run through it and construct a proof-of-concept for some coworkers and figured I'd publish it for the masses. I hope it was helpful.

Building data sequences in C#

Phil Gilmore — Tue, 19 May 2009 20:03:00 GMT

05/19/2009, Phil Gilmore

Beyond the overlap they share with enumerable collections, sequences are mostly unsupported in C#. A notable exception are some of the static methods of the Enumerable class. Check them out. This support is all I need for most sequence work I do. But the support therein is insufficient for anything complex. To augment this support, I have written some extension methods to various CLR classes to add pseudo-support for sequences and sets. One that seems to be especially useful is a sequence generator method. It immediately became useful in many instances, so I thought I'd share it.

What can I do with a sequence generator?

Generate a time-of-day list to allow users to select a time from a drop-down list, perhaps in 15-minute intervals.
Generate a list of months to allow users to select a month from a drop-down list.
Generate a list of years to allow a user to select their birth year from a drop-down list.
Generate a list of any type of sequential data for user selection.
Build an "upline" of parent-child relationships in table of hierarchical data traversed through a self-join.
Any operation that would normally be constructed using a For loop or While loop to populate a list or collection.

Why not collections and loops?

Looking at this list, you might be pondering the usefulness of this since many of these things can be achieved using a collections built in a for-loop or through various Linq maneuvers. This is true. Consider the example above in building an upline from a hierarchical table. But the value of sequence generation is easier to see when considering that sequence data can be built by analyzing the last item in the sequence. For example, you could use a For loop to iterate through your file system and build a List of mp3 filenames in your music collection. This is more the function of a collection than a sequence. This data already exists as separate elements that are found and stored in a collection. If one mp3 file is deleted, the next does not change. In a sequence where elements are related by generation, the removal or change of an element may affect the generation of the rest of the sequence. For example, consider a sequence of incremental integers starting with 1000 and incrementing by 1 with a sequence size of 5. The elements of this sequence would be 1000, 1001, 1002, 1003 1004. If the first element were to change to 1002, the sequence would continue its pattern and become 1002, 1003, 1004, 1005, 1006. The generation of elements in a sequence also does not necessarily require existing data to be collected. Whereas a collection of mp3 filenames requires a filesystem that can be queried to retrieve these filenames, a sequence of incremental integer is generated from only a single seed element (1000 in my first example).

Building a sequence generator:

public static IEnumerable<T> CreateSequence<T>(
    this T startElement, Func<T, T> getNextElement, Predicate<T> isLastElement)
{
    T currentElement = startElement;

    while (!isLastElement(currentElement))
    {
        yield return currentElement;
        currentElement = getNextElement(currentElement);
    }
    yield return currentElement;
}

The first parameter (startElement) is the object on which the method is called. This is probably a primitive object, but can be anything. There are no constraints on the T type parameter so reference and value types are both game. Even literals work. You can call this method on the literal number 1. Of course, this is part of the syntax of C# extension methods. When consuming this method, you do not pass the first parameter. But it's important to understand that this is the first element in the sequence (the seed).

The getNextElement parameter (the first that you provide) is a function. This function can be a delegate to a method, an anonymous method, or a lambda expression. In my examples, I use a lambda expression. The function is given the current element and is expected to return the next element in the sequence. For simple sequences, it will probably just add or subtract some number to the current element to produce the next one.

The isLastElement parameter is another function. As each element is added to the sequence, this function is executed to determine if the end of the sequence has been reached. If the function returns false, then the sequence continues and getNextElement will be called again to get yet another element. If it instead returns true, the current element will be the last element added to the sequence and the CreateSequence method will return thereafter.

Beware of infinite loops when using this. If the IsLastElement function never returns true, you will encounter an infinite loop. For this reason, it may be a good habit to use >= and <= operators instead of == operators, for example. Even though your sequence may be simple as in our examples, better safe than sorry. For more complicated sequences, be even more careful.

The method can be refined if desired. It may be desirable to change the isLastElement predicate from an UNTIL condition to a WHILE condition (and hence renaming it to isValidElement instead), for example.

Using the sequence generator:

Most of these examples can be done using the static methods of the Enumerable class with a little more simplicity. But I'll still keep the examples simple. You can build up to the hard stuff yourself. Here is a simple example using the sequence generator method in an ASP.NET MVC web form where a TIME must be selected. First, the code to generate the view data:

// Create a sequence of times, 15 minutes apart.
DateTime referenceDate = DateTime.Now.Date;
List<DateTime> availableTimes = referenceDate.CreateSequence
(
    x => x.AddMinutes(15), 
    x => x.CompareTo(referenceDate.AddDays(1).AddMinutes(-15)) >= 0
).ToList();

// Convert times to a list of bindable objects for a dropdown list in the MVC view.
ViewData["DueTimesAvailable"] = availableTimes.Select(
    x => new SelectListItem()
    {
        Text = x.ToString("hh:mm tt"),
        Value = x.ToString("hh:mm tt"),
        Selected = x.Equals(referenceDate)
    }).ToList();

The first block of code creates a list of datetimes starting at midnight on the current date, every 15 minutes until 11:45pm on the same day. The second block converts these DateTimes to a List<SelectListItem> using Linq. Here's a simple example, creating a list of month names.

List<string> months = 1.CreateSequence(m => m + 1, m => m >= 12)
    .Select(i => System.Threading.Thread
        .CurrentThread.CurrentCulture
        .DateTimeFormat.GetMonthName(i)
    ).ToList();

Screen shots:

In the example above, we get month names in a sequence ("January", "Februrary", "March"...). Below are some of these examples in action in an ASP.NET MVC page. Notice that Months and Times are in ascending order and Years are in descending order. They were not sorted in this way. They were generated in those orders by either incrementing or decrementing the sequence seed.

So where does this leave sets?

Additional extension methods and classes can be used to treat these sequences and native Enums as sets. Watch for more details in another blog post.

Universal method chaining in C# 3.5

Phil Gilmore — Tue, 07 Apr 2009 23:32:00 GMT

04/07/2009

Phil Gilmore

Here I will present a solution that provides method chaining in C# 3.5. I hope it helps you and I hope that we will see it added as part of the next update to the .NET.

Is it really a big deal?

I've been working more and more with jQuery and have become accustomed to the convenience of method chaining. But when I come back to C# I find that I'm annoyed that method chaining seems to have been left out of the picture, even as many of the newer extension methods were implemented in C# 3.5. It is especially noteworthy that so many of the methods in the IEnumerable<> and List<> classes return void. I have always wanted to do method chaining on the Sort() method for example. Without chaining, a method requires a variable to hold the reference and in many situations this can be a hassle. Here is a useless example of the standard means of using some of these methods:

Standard syntax:

List<int> myList = (new int[] { 5, 4, 3, 2, 1 }).ToList();
myList.AddRange(new int[] { 6, 7, 8, 9, 10 });
myList.Sort();
myList.Reverse();
myList.ForEach(i => i + 1);
myList.Insert(0, 0);

return myList;

You can see in the example above that every operation must be done independently and that a variable declaration is required when chaining isn't allowed. Given the flow of chainable extension methods introduced in .Net 3.5, (take the ToList() method, for example), I would like all methods of the List<> class to be chainable. Then my could would look like this:

Ideal syntax:

return (new int[] { 5, 4, 3, 2, 1 })
    .ToList()
    .AddRange(new int[] { 6, 7, 8, 9, 10 })
    .Sort()
    .Reverse()
    .ForEach(i => i + 1)
    .Insert(0, 0);

Wouldn't that be cool? We can make this possible using extension methods. The problem with this is that you have to write an extension method for every method of every class you want to make chainable. Well, I decided to start with a few of the more useful methods of the List<> class. I quickly realized that they all looked the same and some of the code could be further generalized and reused. Before long, I had a single extension method that all of my extension methods were calling. Here it is:

The Chain method:

public static T Chain<T>(this T source, Action<T> operation) where T: class
{
    operation(source);
    return source;
}

Simple enough. Remember to put this into a STATIC class as is required for every extension method.

So my Sort() method can now return the result from an internal call to this Chain<> method and the consuming code could look just like the hypothetical code I presented above. At this point, I have written all the extension methods that I expected to write. But given the way the implementation worked out, I can now call ANY method on ANY object as a chained method with just a little effort. This was an unexpected side effect. Anyone who has written a few extension methods probably knows that you could go on forever writing extension methods for every type to do any number of things that you may or may not ever use and still you would never run out of methods to write. Since I can chain anything with this single method, I no longer have to worry about thinking of every contingency I may need to add to the List<> class. For example. If someone else writes an extension method to encrypt list data, for example,

List<string> data = LoadStringsFromDatabase().ToList();
data.Encrypt();
return data;

I would normally have to write an extension method to make it chainable if the method returns void. But this is not necessary if you use the Chain<> method.

return LoadStringsFromDatabase().ToList().Chain(s => s.Encrypt());

While a tad more verbose than ideal, it will work under any circumstance with any void method of any object type. So using just the Chain method, let's take another crack at that first example:

Much better:

return (new int[] { 5, 4, 3, 2, 1 })
    .ToList()
    .Chain(s => s.AddRange(new int[] { 6, 7, 8, 9, 10 }))
    .Chain(s => s.Sort())
    .Chain(s => s.Reverse())
    .Chain(s => s.ForEach(i => i + 1))
    .Chain(s => s.Insert(0, 0));

This is not far off from what I wanted. As before, it is only slightly more verbose than using method-specific chaining extension methods, but not much. You will seldom chain so many things or perform such a mundane operation as my example here, but I have found it very useful in common situations, such as ...

Inserting an element into a list at index 0 inline:

drpState.DataSource = Data.GetStates()
    .Chain(lst => lst.Sort())
    .Chain(lst => lst.Insert(0, new State(" --- ")));

Operating on collections of composite anonymous types:

This is useful because you can't reasonably declare a variable or list variable of anonymous types. I know this looks like a bad example because it could be done using Linq-To-Sql, but this is a fair example because TDS has a 2100 element limit which the .Contains() clause can violate if not handled carefully and this is one solution that may be used:

List<object> idList = (
    from od in db.OrderDetails
    where o.OrderID.Equals(orderID)
    select new { ID = od.OrderDetailID, Name = od.Name, Number = od.DetailNumber }
).ToList().Chain(
    lst => lst.RemoveAll(
        i => subpoenaIDList.Contains(i)
    )
).Cast<object>().ToList();

Modifying properties of a data entity when passing it as a parameter:

db.Orders.Add(myOrder.Chain(o => o.LastUpdated = System.DateTime.Now));

Target ambiguity:

An issue that deserves mention is target ambiguity. There are two ways that chaining can be implemented. The first is where the source is modified and then returned (such as is the case in my method), and the second is where the source is duplicated, modified, and the new copy is returned, leaving the original data intact. Both can be implemented using the method I outlined in this post.

The important point to make is that it should be obvious to the user which behavior your chain method is using. I have failed in this regard and encourage you to improve on the concepts I have outlined here.

Many developers subscribe to a school of thought that one method should be used and the other should not. Feel free to do it either way you like. I personally prefer to return a copy rather than a modified original source and may yet modify my method to do so.

Phil Gilmore ( www.interactiveasp.net )

Reusable Fixture in C#

Phil Gilmore — Thu, 12 Mar 2009 20:23:00 GMT

Phil Gilmore

I was recently working on an application that had had 2 problems. I found that at one level the code repeats itself many times over. Every method in the business layer used the same try / catch / catch structure to wrap calls to the data layer. They were all 95% identical to each other. In another level, some WCF connections were not being closed properly in all instances. Both issues were fixture issues. I found that I could fix them both with a minimum of code repetition when using fixture. Let me show some examples of what was being done with the exception handling structures. There are methods that return a type and some return void. I'll show both.

public ReturnType1 Method1(long barcode)
{
    try
    {
        DataProvider dp = new DataProvider();
        return dp.Method1();
    }
    catch (ApplicationException aex)
    {
        LogWriter.LogException(aex);
        throw new Exception(aex.Message);
    }
    catch (Exception ex)
    {
        LogWriter.LogException(ex);
        throw new Exception("An unhandled server exception was encountered.");
    }
}

public void Method2(long id)
{
    try
    {
        DataProvider dp = new DataProvider();
        dp.Method2(id);
    }
    catch (ApplicationException aex)
    {
        LogWriter.LogException(aex);
        throw new Exception(aex.Message);
    }
    catch (Exception ex)
    {
        LogWriter.LogException(ex);
        throw new Exception("An unhandled server exception was encountered.");
    }
}

You see that in the two methods above, the entire method body is identical except for the content in the actual try { } block. That much repetition is verbose, error-prone, harder to read and unnecessary. It's easy to see how several WCF service calls would end up looking very repetetive too.

public void CallWCFMethod()
{
    ServiceClient client = new ServiceClient();
    try
    {
        try { 
            client.Method1(); 
        } catch Exception(ex) {
            LogError(ex); 
        }
    }
    finally
    {
        try
        {
            client.Close();
            if (client is IDisposable)
                ((IDisposable)client).Dispose();
        }
        catch { Log("WCF connection closed in a faulted state."); }
    }
}

I realize that many of you will want to argue that WCF client should be instantiated in a Using block. Some others will say that the dispose method will call the Close() method.

In the code above, the only line that differs between methods is the line that actually calls client.Method1(); All other lines would be present in every method that consume that WCF service. There is a lot of wasted code here.

The common thread in these two scenarios is that the functional part of each method differs, but the fixture is the same. The fixture is the code that runs before and after the functional code to set up in preparation for the call and to clean up after the call. This can be done using a callback.

To solve this, we need a method that contains the fixture, which we need only write once. Inside the fixture, a callback method will be used to execute code you specify. That code can be anything and is determined at the time of the call. The fixture method doesn't have to know what it is. Using generics and anonymous methods, this syntax is also reasonably readable.

Consider this solution for the first scenario, the exception handlers.

public TResult HandleExceptions<TResult>(Func<TResult> operationCallback)
{
    try
    {
        return operationCallback();
    }
    catch (ApplicationException aex)
    {
        LogWriter.LogException(aex);
        throw new Exception(aex.Message);
    }
    catch (Exception ex)
    {
        LogWriter.LogException(ex);
        throw new Exception("An unhandled server exception was encountered.");
    }
}

Notice that the only parameter for this method is a callback (also known by many other names- function pointer, delegate, etc.). The point is that you pass it in and it is called inside the try { } block. To consume this fuxture method, you just pass your functional code (which used to be inside the try { } block) as a parameter.

public ReturnType1 Method1(string itemCode)
{
    return HandleExceptions(
        delegate()
        {
            DataProvider dp = new DataProvider();
            return dp.Method1;
        }
    );
}

public void Method2(string itemCode)
{
    HandleExceptions(
        delegate()
        {
            DataProvider dp = new DataProvider();
            dp.Method2;
            return 0;
        }
    );
}

For those unfamiliar with this syntax, the delegate() { } part says that the code between curly braces { } is a method that will be passed as a parameter to HandleExceptions. In a strict world, I would have to specify the return type as delegate<ReturnType1> or delegate<int>(). Likewise, the Method1<ReturnType> and Method2<int> declarations would be required with type parameters.

As it is, however, our friend Type Inference determines what those type parameters should be and renders them optional. This is not only nice in a time-saving capacity, but in other situations may also lead to further code reuse.

Here is an example of a provision of reusable fixture for the aforementioned WCF call.

public TResult CallWCFMethod<TResult>(Func<ServiceClient, TResult> operationCallback)
{
    ServiceClient client = new ServiceClient;
    try
    {
        try { 
            return operationCallback(client);
        } catch Exception(ex) {
            LogError(ex); 
        }

    }
    finally
    {
        try
        {
            client.Close();
            if (client is IDisposable)
                ((IDisposable)client).Dispose();
        }
        catch { }
    }
}

All we've done is coded the input func<> parameter with the type of the parameter that will be passed to operationCallback, and then changed the functional try { } block to call the operationCallback function, passing the service client object as a parameter. You can easily put any additional logging, setup or teardown requirements for all WCF calls in just one place. It is now a simple matter to call any method in the WCF service without constantly opening and closing the connection each time, without the ridiculous exception handling that WCF calls require, and without incessant logging calls. Subsequent calls are all very terse and easy to understand. They look like this:

public void WCFMethod1()
{
    CallWCFMethod(
        delegate(ServiceClient client)
        {
            client.Method1();
            return 0;
        }
    );
}

Of course, the above example is for a void call. Any call that actually returns something can have the return type inferred and returned as the result of the CallWCFMethod method as already shown in the exception handler example above and in the following example.

public ReturnType1 WCFMethod2()
{
    return CallWCFMethod(
        delegate(ServiceClient client)
        {
            return client.Method2();
        }
    );
}

Phil Gilmore ( www.interactiveasp.net )

Advanced merging - manual alignment with KDIFF3

Phil Gilmore — Mon, 23 Feb 2009 21:41:00 GMT

Phil Gilmore

Not all merge programs are equal. Where possible, it's nice to have the merge program automatically resolve any conflicts that it can before forcing you to make any manual merge selections. Of the tools that I've used, KDIFF3 always does the best automatic merge. When auto merge fails, it's usually still very easy to select the desired merge source when resolving a conflict.

On rare occasions, KDiff3 will match common lines in the first place where you wanted to match in the second place. If it matches in a place other than where you want it to, you will need to do a manual alignment. This is easy to do in 2-way diff operations, but can raise some questions when doing a 3-way merge. Here I show you how to do it in an example of why you would want to do it.

Sample Sources

Here are the sample sources I will use to demonstrate manual alignment.

Load them up into KDIFF3.

Initial alignments

You now see the initial alignments that KDIFF3 comes up with.

The first line that is common across all 3 sources is the line containing the number "1". But what if we want it to match up lines starting with the letter "A" instead? We have to tell it where to line up the 3 sources. Do this with a manual alignment. You can access it from the menu, but it's easier to do this with the hot key combination, CTRL-Y. If you screw it up, just press CTRL-SHIFT-Y to reset your manual alignments and start over. If you insist on using the menu, you can see the options for manual alignment in the screen shot below.

Manual alignments are done on 2 sources at a time. This makes it confusing for a 3-way merge. You actually achieve a 3-way alignment as a series of two 2-way alignments.

Sequence for a 2-way manual alignment:

1	Click on the line to be aligned in the first source with your mouse. You will not see it receive focus nor a cursor. There will be no indication that the click took place. Have faith that it did take place and move on to step 2.
2	Press CTRL-Y to start the manual alignment.
3	Click on the line to be aligned in the second source with your mouse.
4	Press CTRL-Y to complete the manual alignment.

First manual alignment

Warning: If you wish to save the merge result when finished, you should start a merge before adding manual alignments. Starting a merge will reset any manual alignments. I do not show a merge in these screen shots for the sake of keeping the images as small as I can

Here is the first manual alignment. Starting from KDiff's Initial alignment (right after loading the sources), click on the first line, annotated with a "1" in bright red. Press CTRL-Y then click the second source on the line annotated with a "2" in bright red. Press CTRL-Y to complete the alignment.

After the completion of the operation, you see the alignment between the first and second sources. The "A" on the first two sources are aligned on the same line. The third source has been realigned with the other sources where possible. The first line is the "1" line. It cannot align with the "1" line in sources 1 and 2 because it would violate the manual alignment to line up all 3. The same applies to the "2" and "3" lines. The first line that can be aligned across all 3 sources is the "4" line. Lines "5" and "6" follow suit and you are left with what you see here.

Second manual alignment

Below are the alignment points for the second alignment. Hopefully, at this point you understand the process well enough that you didn't need this screen shot to tell you what's next.

The second alignment brings all the "A" lines together. Below is the final result.

Remember that if you are doing a merge and you did not start the merge before the alignments, starting a merge at this point will reset your manual alignments.

Happy merging.

Phil Gilmore (www.interactiveasp.net)

Lambda expressions tutorial for C# and Visual Studio 2008

Phil Gilmore — Sat, 10 Jan 2009 03:31:00 GMT

Phil Gilmore

Lambda expressions are one of the cool new features of .NET 3.5 and are available in the C# compiler inside Visual Studio 2008. They can make code more readable and permit the framework to provide some really neat functionality when mixed with other .NET features like generics and anonymous methods.

Lambda expressions look strange at first, though, and are often hard for newcomers to understand. I saw several presentations of lambda expressions before I saw Nathan Zaugg's presentation which finally got through to me. I will attempt to describe them the way he described them in hopes that many more developers can benefit from this concept.

I will start with a description of lambda expressions and an example of how to compose one. I will then provide some examples of evolution of the C# language to demonstrate how we came to lambda expressions and thus show how you to make the transition from using the old methods to using lambda expressions.

A lambda expression is a shorthand syntax for an anonymous method.

An anonymous method is a method body that is defined in place, rather than given a name and called by name elsewhere.

Here is are some lambda expressions:

i => i * i

(i1, i2) => i1 + i2

parm => MessageBox.Show(
    "Do you want to save the file: " + parm + "?", 
    "Confirm file save", MessageBoxButtons.YesNo)

In the above expressions, the presence of the => operator makes it a lambda expression. On the left side of the expression is a parameter list. On the right side is an expression to be evaluated. The expression may contain the parameters that were defined on the other side of the => operator.

In essence, lambda expressions define a function's parameters and its body. It has the limitation that the body must be a single expression which returns a single object. They can be used anywhere a delegate would be used. They are callback methods.

Here is a demonstration of the evolution of C# from callbacks to lambda expressions. In these demonstrations, I will define the following code, which I will reuse in each example:

public delegate int IntCallback(int parameter1, int parameter2);

protected int AddIntegers(int value1, int value2)
{
    return value1 + value2;
}

First, I declare a delegate which takes two integer parameters and returns an integer. Then I define a method that matches this delegate signature, AddIntegers(). I go on to define a method that uses such a callback. Any code that calls this method must pass a callback of the IntCallback delegate type.

protected int CalculateSum(IEnumerable<int> values, IntCallback callback)
{
    int result = 0;
    foreach (int value in values)
        result callback(result, value);
    
    return result;
}

Finally, I declare a small integer sequence for use in the demonstrations.

List<int> intData = new List<int>(
    new int[] { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 });

I will start with a traditional callback. This passes a delegate instance of AddIntegers as the callback to CalculateSum. CalculateSum will repeatedly call AddIntegers and return the sum of all numbers in the intData sequence.

IntCallback callback = new IntCallback(AddIntegers);
int total = CalculateSum(intData, callback);

In recent versions of Visual Studio, you do not have to invoke the constructor of the delegate type to create an instance of it when passing as a method parameter. The compiler is smart enough to instantiate it based on the prototype of the parameter in question.

int total = CalculateSum(intData, AddIntegers);

In Visual Studio 2005, Anonymous methods were introduced, allowing you to declare the callback method body in place. Using anonymous methods, the AddIntegers method is no longer used. Instead, its body is declared in place.

int total = CalculateSum(intData, 
    delegate(int value1, int value2) 
    { 
        return value1 + value2; 
    }
);

Using the delegate keyword here tells the compiler that a parameter list and method body follow. The parameter list and return type of this method must match the signature of the delegate for this parameter (IntCallback), or you will get a compiler error. Notice that this syntax is identical to a normal method except for the return type and the method name are missing.

The next evolution was a lambda expression, which is a shorthand notation for the anonymous delegate shown above. Let's analyze the anonymous method and convert it to a lambda expression.

delegate(int value1, int value2) 
{ 
    return value1 + value2; 
}

In the above code, the parameter list is:

(int value1, int value2)

This becomes the left side of our lambda expression.

(value1, value2) =>

The types are usually omitted. This is because as the lambda expression is passed as a parameter whose type is a delegate, the parameter is already defined as a method with certain parameters. In this case, the parameter is an IntCallback, and IntCallback defines a parameter list of (int value1, int value2). Given that, the compiler uses type inference to determine the types of the parameters in the lambda expression. The return type is dermined in the same way.

Next we extract the method body. This is the right-hand side of the lambda expression. This is sometimes called the predicate. This should not be confused with any parameter whose name is predicate. In such instances, a complete lambda expression is expected.

Here is the method body, extracted from the anonymous method.

return value1 + value2;

Given that, we can complete our lambda expression. Remember that the predicate is a single expression rather than a multitude of instructions. Hence, we do not use the return keyword.

(value1, value2) => value1 + value2

When this method is passed to CalculateSum, CalculateSum will call the the method which was passed in as parameter callback. This passes the value1 and value2 parameters to our lambda expression, which plugs them in and evaluates the expression value1 + value2 and returns the result to the caller (CalculateSum).

int total = CalculateSum(intData,
    (value1, value2) => value1 + value2
);

Phil Gilmore (www.interactiveasp.net)

Regular expression for email addresses (replacing the Visual Studio 2008 default).

Phil Gilmore — Fri, 09 Jan 2009 18:19:00 GMT

Phil Gilmore

I recently had a user report that they couldn't register on my client's site. The site's registration page reported that their email address was invalid. The email address was indeed strange but valid nonetheless. We were using a regular expression validator control to check the email address on registration. The problem is that the regular expression that Visual Studio designer put in there for email addresses doesn't recognize it.

Here is the regular expression that the Visual Studio 2008 designer conveniently put into the page on our behalf.

\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*

This has the following problems:

Rules only apply at a single point in the input. Any character can preceed or follow any valid email address including spaces, punctuation characters, periods, @ symbols, etc. For example, the input ~!@#$%^&*()_+=-[]{}';":/.,?>< nobody@nowhere.com~! @#$%^&*()_+=-[]{}';":/.,?>< would pass this validation.
User name may contain multiple consecutive periods. For example, the input nobody..lives........here@nowhere.com would pass this validation.
Domain name may contain multiple consecutive periods after the first single period. For example, the input nobody@nowhere.co....uk would pass this validation.
Many valid email addresses will not pass this validation. For example, the input nobody-@nowhere.com would fail.

Obviously, there are some flaws here. If you are familiar with regular expressions, you can see immediately that it's missing the ^ and $ restrictions, for example. Rather than try to massage this one into compliance, I started with a new one. There are probably a million of these on the web and no doubt some are better than mine. But I thought I'd blog it anyway since it's done and working. Here is what I came up with.

^([\w-_]+\.)*[\w-_]+@([\w-_]+\.)*[\w-_]+\.[\w-_]+$

This regular expression has the following attributes:

User name must be one character or more.
User name may contain one ore more periods.
User name must not begin or end with a period.
Double contiguous periods are not allowed in the user name.
User name must only contain characters a-z, A-Z, 0-9, hyphens, underscores and single periods.
Domain name must be three characters or more.
Domain name must contain one or more periods.
Domain name may not begin or end with a period.
Double contiguous periods are not allowed in the domain name.
User name must only contain characters a-z, A-Z, 0-9, hyphens, underscores and single periods.
And single @ symbol is required between the user name and the domain name.
Allowed special characters (hyphen and underscore) are permitted at any frequency anywhere in the user name or domain name.

Of course, you may choose to add more allowed special characters. Although I've never seen one in an email address, you may need to allow the plus (+) character, for example. This is easy. Just change all instances of \w to \w\+ and it will permit it.

I tested this regular expression against all the email addresses in the client's user database (about 5500 addresses). All email addresses that failed were either obviously invalid or outright blank (imported from another process, never validated against a regular expression). Out of 5500 email addresses, only 9 failed which weren't blank and they were all invalid.

Phil Gilmore (www.interactiveasp.net)

FreePascal Error: Illegal parameter: -Opentium3

Phil Gilmore — Mon, 05 Jan 2009 18:44:00 GMT

Phil Gilmore

I was trying to build an existing Delphi DLL as a 64-bit DLL using FreePascal 2.2.2. I opened the .dpr file which is as simple as a DLL project can get. I clicked Compile, then Build. The build failed on line 0 with the error "Illegal parameter: -Opentium3". This is frustrating to see on a fresh installation with a simple project (simple on the level of Hello-World). I dug just a bit and found a bug tracker entry for it which provides some insight, but didn't really provide a resolution. I have gleaned the resolution from the bug entry and provide a walk-through here.

Incidentally, if you try to build twice, the second and subsequent times will return a different error: "Unable to open file C:\...\fp.cfg". This is because the first error interrupted the program and left the cfg file open. You will have to close the IDE to release it. Do not edit the cfg file as it states. It is generated every time you build from the IDE.

Here is the bug entry:

http://bugs.freepascal.org/view.php?id=11865

As Marco van de Voort pointed out on that page, changing the -Opentium3 option to contain a double "p" will fix this issue. It also shows that the problem has been resolved in the next version, 2.2.3 (which is not the current stable release as of this writing). It also indicates that the problem was fixed in the previous version, but the fix did not proliferate to version 2.2.2 (I have not double-checked this). Lastly, it indicates that this problem exists when Win32 (Windows XP).

Steps to reproduce:

1) Open your FPC IDE. Load a project to build.

2) From the menu, click Compile, then Build.

3) You should see the failure in the build status dialog.

4) Clear the build status dialog and you can see the error in the messages frame:

If you run this more than once, you will instead see the message:

"Unable to open file C:\...\fp.cfg"

See notes above.

Steps to resolution:

1) Open your FPC IDE. Load a project to build.

2) From the menu, click Options, then Compiler....

3) In the compiler options dialog, Find the additional compiler args field at the bottom.

Change the -Opentium3 to -Oppentium3 (with two "p"s).

3) Click the OK button to close the dialog.

4) Close the IDE.

5) Repeat the "steps to reproduce" steps 1 and 2.

6) You should now see a successful build dialog.

Happy coding.

Phil Gilmore (www.interactiveasp.net)

How to configure MKS to use KDiff3

Phil Gilmore — Fri, 07 Nov 2008 22:44:00 GMT

Phil Gilmore

One of my clients is using MKS for source control and task management. I have configured the source control system on my workstation to use KDiff3 for diff and merge operations. I couldn't find any information on the command line to use and could find very little information on the parameters that are made available by MKS to pass to third party tools.

It took some effort to figure this out and I could find very little information on how to configure MKS to use third party tools so I decided to share this information here. I think it might also be useful to show all this in case anyone wants to repeat the process to configure some other third party tool to integrate with MKS, such as WinDiff or WinMerge.

You can find information about configuring KDiff3 here.

http://kdiff3.sourceforge.net/doc/documentation.html#id2488514

Here is a snippet of the pertinent part:

To see all available command line options type

kdiff3 --help

Example output:

Options:
  -m, --merge               Merge the input.
  -b, --base file           Explicit base file. For compatibility with certain tools.
  -o, --output file         Output file. Implies -m. E.g.: -o newfile.txt
  --out file                Output file, again. (For compatibility with certain tools.)
  --auto                    No GUI if all conflicts are auto-solvable. (Needs -o file)
  --qall                    Don't solve conflicts automatically. (For compatibility...)
  --L1 alias1               Visible name replacement for input file 1 (base).
  --L2 alias2               Visible name replacement for input file 2.
  --L3 alias3               Visible name replacement for input file 3.
  -L, --fname alias         Alternative visible name replacement. Supply this once for every input.
  --cs string               Override a config setting. Use once for every setting. E.g.: --cs "AutoAdvance=1"
  --confighelp              Show list of config settings and current values.
  --config file             Use a different config file.

Given this, you need only know which MKS variables to substitute for each of the KDiff3 parameters from the table above when you construct your command line to the third party tool. This is the tricky part.

To specify the command line, open MKS and click File -> Edit preferences, then traverse the navigation tree to the /MKS Source/Diff and Merge Tools node. On that page, you can specify the command line for your preferred diff tool and your preferred 3-way merge tool. There are predefined configurations for several popular tools to choose from here (AraxisMerge and Beyond Compare, for example).

The only documentation I found about MKS command-line variables is in the context-sensitive help (click the Help button). Here is what it says.

You can supply the following arguments for the command to control how the third party tool operates:
♦ {0} to display the title of the common ancestor object of the files being merged.

♦ {1} to display the title of the file being merged from.

♦ {2} to display the title of the file being merged to.

♦ {3} to display the title of the working file.

♦ {4} the path to the common ancestor object of the files being merged.

♦ {5} the path to the file being merged from.

♦ {6} the path to the file being merged to.

♦ {7} the path to the working file.

♦ {8} the path to the output file. You can use this argument to save the merge results in a file other than the working file.

Each argument must be quoted. For example, the command line for the ABC Merge tool could be:
abcmerge.exe "{4}" "{7}" "{5}"

This information raises several questions. For example, what is the difference between parameters 6 and 8? Aren't both of them a target file to contain the merge results? Which one should one use? The same question arises between 5 and 7.

To determine which parameters I wanted to use, I had to determine what their values would be and how MKS would behave when writing the merge results to various targets. To do this, I wrote a simple program to show me the values that are passed to its command line. I can plug this program in where I would normally use a shelled program such as a diff or merge tool.

Here is the (Delphi) source for it:

program CommandLineInfo;

{$APPTYPE CONSOLE}

uses
SysUtils,
Windows,
Classes;

var
j: integer;
pc: integer;
output: TStringList;
begin
output := TStringList.Create;
try

    pc := ParamCount;
    output.Add(paramstr(0));
    output.Add('');
    for j := 1 to pc do
      output.Add(IntToStr(j) + ': ' + ParamStr(j));

    MessageBox(0, pchar(output.Text), pchar('Command-line info'), MB_OK);

finally
    output.Free;
end;
end.

If you're one of the unfortunate souls who does not use Delphi, download the binary of the aforementioned CommandLineInfo application here. You can run the application without any installer prerequisites.

When plugged in with this command line:

C:\Archive\Apps\CommandLineInfo.exe "{0}" "{1}" "{2}" "{3}" "{4}" "{5}" "{6}" "{7}" "{8}"

I get these results:

I found that if you do not save the merge result to the working file, MKS assumes that you did not save your changes (it tells you that the working file was not modified). Hence your merge results must be written to the working file. You cannot see it in the screen shot above because I have blurred them out, but item 7 and item 8 (seen above as 8: and 9:) have identical values. They are both pointing to the working file. This way, the merge result is saved in the working file. If the blurs above hinder your purposes, you can retrace the steps I've outlined in this article to see the results for yourself.

Ultimately, these are the command line entries that I constructed.

Diff:

C:\Program Files\KDiff3\kdiff3.exe "{3}" "{4}" --L1 "{1}" --L2 "{2}"

3-Way Merge:

C:\Program Files\KDiff3\kdiff3.exe "{4}" "{5}" "{7}" -o "{8}" --L1 "{0}" --L2 "{1}" --L3 "{3}"

Phil Gilmore (www.interactiveasp.net)