C#

Using conversion operators to create flexible types

Follow along with me. Have you ever had a situation where you had to represent some conceptually complex or flexible value in a class? For instance, the the concept of “hours”? Maybe you would start off simple with something like:

public class Foo
{
    public decimal Hours { get; set; }
}

//usage
foo.Hours = 1;
foo.Hours = 1.5m;

You were clever to note that hours may be used as whole numbers or fractions, so you made sure  you could assign int and decimal values. But it turns out your data is more complex than that. You also must account for string representations of hours, such as “1:30” (one hour and thirty minutes).

Easy enough. It’s probably time to create a custom class or struct to encapsulate all that. If you’re not familiar with implicit or explicit conversion operators, you may end up with a simple class with overloaded constructors that accept int, decimal, or string, so that it could be used like this:

hours = new Hours(1);
hours = new Hours(1.5m);
hours = new Hours("1:30");

decimal hoursAsDecimal = hours.Value;

It works. But this is kinda lame. Wouldn’t it be cool if you could just do something like this:

hours = 1;
hours = 1.5m; 
hours = "1:30";

decimal hoursAsDecimal = hours;

You can!

Understanding conversion operators

To quote MSDN: C# enables programmers to declare conversions on classes or structs so that classes or structs can be converted to and/or from other classes or structs, or basic types. Conversions are defined like operators and are named for the type to which they convert. Either the type of the argument to be converted, or the type of the result of the conversion, but not both, must be the containing type.

Here’s a basic Hours struct that has just one conversion operator:

public struct Hours
{
    private readonly decimal _hours;
    private Hours(decimal hours) { _hours = hours; }

    //implicit decimal to Hours conversion operator
    public static implicit operator Hours(decimal value)
    {
        return new Hours(value);
    }
}

This implicit operator is specifying that types of decimal can be implicitly converted into types of Hours, and the method body is how the conversion is performed (in this case, decimal is the underlying type, so it just returns a new Hours instance).

To allow other values to be converted, just specify additional implicit operators:

//implicit int to Hours conversion operator
public static implicit operator Hours(int value)
{
    return new Hours(value);
}

//implicit string to Hours conversion operator
public static implicit operator Hours(string value)
{
    //Parse() is the private method of Hours responsible for
    //converting the string to a decimal. It's omitted for brevity
    return Parse(value);
}

Switching things around

Every operator above defines how a particular type can be converted into the custom type Hours, but what about the other way around? How can we make Hours directly assignable to a decimal type? All you have to do is flip it around.

//implicit Hours to decimal conversion operator
public static implicit operator decimal(Hours value)
{
    return value._hours;
}

Again, this is defining that the type Hours can be implicitly converted into type decimal. The net result of this and the other operators defined above is that you can write super flexible and clean code:

hours = 1;
hours = 1.5m; 
hours = "1:30";

decimal hoursAsDecimal = hours;

A quick note about explicit operators

You can also make operators explicit. They work the same way, but require an explicit cast to work.

//explicit decimal to Hours conversion operator
public static explicit operator Hours(decimal value)
{
    return new Hours(value);
}

//usage
hours = (Hours) 1.5m; //explicit cast from decimal to Hours

hours = 1.5m; //compile error, "cannot convert decimal to Hours"

Because of this, implicit operators are generally preferred, but if you want callers of your code to be explicitly aware that they must cast properly you can do so.

Next time you find yourself creating a custom chameleon-like type that must be assignable to or from several different types, consider encapsulating all of the conversion code by putting it into the type and then creating implicit or explicit conversion operators to make the calling code clean, easy and flexible.

String to array, array to string

This post is more of a reminder for me than it is some enlightened tutorial. I simply have a mental block when it comes to remembering which methods to use when converting a delimited string into an array and vice versa. Here’s my reminder.

Converting a delimited string into an array

A delimited string can be converted into an array with the String.Split() method. It accepts a character array. You can pass a single character delimiter in single quotes – not double –  and the framework will handle it for you.

string commaString = "separated,by,commas,";
string[] arrayOfStrings = commaString.Split(',');

//Result: [separated][by][commas][]

To prevent empty elements, provide the appropriate StringSplitOptions enumeration. Annoyingly, this overload doesn’t work when providing a single character delimiter. It must be provided as a character array.

string commaString = "separated,by,commas,";
char[] delimiter = new char[] { ',' };
string[] arrayOfStrings = commaString.Split(delimiter, StringSplitOptions.RemoveEmptyEntries);

//Result: [separated][by][commas]

When you have a multi-character delimiter, splitting must be done with a string array thusly.

string bracketString = "[separated][by][brackets]";
string[] arrayOfStrings = bracketString.Split(new string[] { "][" }, StringSplitOptions.None);

//Result: [separated][by][brackets]

Converting an array to a delimited string

An array can be converted into a delimited string with the static String.Join() method. It accepts the string you wish to delimit with and an array of strings.

string[] arrayOfStrings = new string[] { "one", "two", "three" };
string delimitedString = string.Join(",", arrayOfStrings);

//Result: "one,two,three"

You can also join an IEnumerable<string>.

List<string> stringList = new List<string>() {"one", "two", "three" };
string delimitedString = string.Join(", ", stringList);

//Result: "one, two, three"

End.

Build your own CMS – Iteration 1: Data Model, Templates, Content Creation

This is the fourth post in a series documenting my development and implementation of a content management system (CMS) built on the ASP.NET MVC Platform.

This content management system will be built iteratively. Iteration 1 is far from a complete solution, but it is already fully functioning as a CMS. This post will discuss the current (simple!) database architecture and the concept of (straightforward!) templating. Then I’ll move on to how the admin site (dynamically!) provides a way to create and edit content pages.

The database

It doesn’t get any simpler than this. If you exclude the Languages table which is only there to support the future localization features of the CMS, we’re only working with two tables.

CMS database

ContentPages – this contains all content “page” records, which currently consists of the page’s URL alias, and the XML-based template name.

ContentPages table

ContentItems – this contains the actual content associated with a page. Each content record is for a specific language and contentid. The contentid is the identifier of a “content item” element in the XML template file. More on that below.

 ContentItems table

Languages – this should be self-explanatory. I’ll be discussing this in depth in future posts. For now just relax, everything is going to have a language id of “1” – English.

Template-driven content

XML-based templates determine the set of “content items” that defines a type of page. Below is the Product template:

<?xml version="1.0" encoding="utf-8" ?>
<template name="Product">
    <contentItems>
        <include template="_Includes\PageMaster.xml" />
        <content id="Title" type="text" isHtml="false"></content>
        <content id="Body" type="textarea" isHtml="true"></content>
        <content id="PrimaryImageUrl" type="text" isHtml="false"></content>
    </contentItems>
</template>

The id attributes define the unique id of the content item and this corresponds to the contentid column in the ContentItems database table. The other attributes are metadata that describes what type of content item it is. These are used in the CMS Administration application to render and validate the proper field type (when creating/editing a page), and by the client web site to render the content.

Templates support nesting, which provides the flexibility to define content items that may be used by multiple templates. The <include> element tells the system to pull in the content items from the included template.

The PageMaster template consists of a few globally used content items:

<?xml version="1.0" encoding="utf-8" ?>
<template name="PageMaster">
    <contentItems>
        <content id="PageTitle" type="text" isHtml="false"></content>
        <content id="MetaKeywords" type="text" isHtml="false"></content>
        <content id="MetaDescription" type="text" isHtml="false"></content>
    </contentItems>
</template>

This means a Product page consists of 6 total content elements: PageTitle, MetaKeywords, MetaDescription, Title, Body, and PrimaryImageUrl.

The CMS Administration Application

Oh yes, I brought a chart.

CMS architecture

This is mostly marketing BS – an attempt to fool you into thinking I know what I’m doing. Okay, I’m only half-kidding. The reality is that some of the lines between components here are blurred and, as this is just iteration 1, it will likely change. The basic idea is this:

(MVC App + Template Files + Data) * Awesome = CMS

Below is an example of the “Create Content Page” page. Select a template, select a language, and the Page Content items are loaded up and dynamically* a form gets rendered. Select a URL alias for the page, fill out any content fields, save – done!

Create Content Pag

*Rendering this form dynamically is a double-edged sword. It’s great because after coding this just once, end users can create and edit an infinite number of pages with an infinite variety of templates. However, with many fields this form could get a bit unwieldy. Users might have trouble finding the field that corresponds to the part of the rendered page they are attempting to edit. Therefore, I’m also going to build an override system where a developer can explicitly design and layout the fields of a particular template in any way they see fit. A double-edged sword of awesome.

I’m just going to post pseudo-code, as it would be a bit much to include in full. The form gets rendered in a spirit similar to Dynamic forms with ASP.NET MVC and XML. The Controller retrieves the template and passes it to the view, which in part might look something like this:

<div>
    <fieldset>
       <legend>Page Content</legend>

            <%foreach(var item in Model.Template.ContentItems) { %>
                <div class="editor-label">
                    <%=item.Id %>
                </div>
                <div class="editor-field">
                    <!-- hiding logic to select the proper input type/style 
			    based on attributes of ContentItem -->
                    <%=Html.TextBox(item.Id, item.value) %>
                </div>
            <%} %>

            <input type="hidden" name="templateName" value="<%=Model.Template.Name %>" />
            <input type="submit" name="submit" value="Create Page" />

    </fieldset>
</div>

The form is posted to a controller that does something along the lines of:

[HttpPost]
[ValidateInput(false)]
public ActionResult CreateNewPage(string alias, string templateName /*, form data */)
{
    var template = TemplateManager.GetTemplate(templateName);

    var contentItems = MapFormFieldsToTemplateAndCreateListOfContentItems();

    _repository.CreateContentItems(contentItems);

    return RedirectToAction("success");
}

Once this is successfully saved to the database, the data looks something like this:

image

The page edit mechanism works the same way, only with the added step of having to query the content for a given contentpageid. With the magic of the (not) patent-pending “Template Transformation Engine”, the data is wired up with the template into a nice moist ball of content goodness.

//get page by id
var contentPage = _repo.ContentPages.Query
    .Where(x => x.Id == theContentPageIdToEdit)
    .SingleOrDefault();

//get the template metadata by template name (xml file lookup)
var template = TemplateManager.GetTemplate(contentPage.TemplateName);

//loop through each item in template, find matching item within the page content
foreach (var templateContentItem in Template.ContentItems)
{
    var contentItem = contentPage.ContentItems
        .Where(c => c.ContentId == templateContentItem.Id)
        .SingleOrDefault();

    //templateContentItem & contentItem is everything we need to
    //render the hydrated and formatted form field for this piece of content
}

And this brings us to the next discussion: how the client website for our fictitious company, GlobalBeers, retrieves and renders this content on its pages. Stay tuned!

Regular expression performance comparisons

Pop quiz, hotshot. You need to match a string using a regular expression and you need it to execute as fast as possible. Application startup time doesn’t matter and each method will execute 10,000 times. Which option do you chose?

//A
void Method_A()
{
    Regex x = new Regex("somepattern");
    x.IsMatch("test.string!");
}

//B
void Method_B()
{
    Regex.IsMatch("test.string!", "somepattern");
}

//C
static void Method_C()
{
    Regex x = new Regex("somepattern");
    x.IsMatch("test.string!");
}

//D
static readonly Regex regexForMethod_D = new Regex("somepattern");
public void Method_D()
{
    regexForMethod_D.IsMatch("test.string!");
}

//E
static readonly Regex regexForMethod_E = new Regex("somepattern",
	RegexOptions.Compiled);
public void Method_E()
{
    regexForMethod_E.IsMatch("test.string!");
}  

Bonus question: two pairs of these options take just about the same time to execute. Which are they, and which pair is faster? The answers are below.

Note: for brevity, I’ve listed “somepattern” as the regex pattern. For my actual testing, I used a pattern to match an email address – the one in the code sample just below.

Programming regular expressions by coincidence

I’ll admit, regular expressions intimidate me just a little. They’re powerful and fast, but the complex, archaic-looking patterns just make me want to avoid them. When I did have to use a Regex, I would just google for a piece of code, confirm that it generally worked and move on.

//need to validate an email... [copy/paste from a website:]
Regex x = new Regex(@"\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*");
x.IsMatch("e@mail.com");
//it works... moving on

This is the definition of programming by coincidence. Regular expressions are somewhat complex. Initialization of a Regex object is not a trivial operation, and then there’s that whole question of whether you should compile or not.

You can get away with programming by coincidence most of the time. When your servers are melting in a giant ball of fire because your website is initializing and compiling several regular expressions on every request… you can’t.

Regular expression options for an ASP.NET application

This article deals with regular expressions in a general matter, but I want to focus on using them on the context of an ASP.NET website: A application that is typically long-running, and has several global (static) classes/members as well as instance objects (such as a web form Page) in which a regular expression may be used.

Static vs Instance members

The first thing to consider is whether your regular expression object should be defined as an instance member, or as a static member. Unless the Regex pattern is variable or only ever used once, I can’t think of a reason why you would ever want to create a Regex as an instance variable in an ASP.NET application.

As a general rule of thumb, create regular expressions as static read-only objects if they are going to be executed several times. D is much faster than A.

//A
void Method_A()
{
    Regex x = new Regex("somepattern");
    x.IsMatch("test.string!");
}

//D
static readonly Regex regexForMethod_D = new Regex("somepattern");
public void Method_D()
{
    regexForMethod_D.IsMatch("test.string!");
}

I’m currently maintaining code that has a lot of the following in it: A static method that initializes a local regular expression within it. When I was programming by coincidence, I’d see this and at first be taken aback “a non-static Regex – this is probably slow because it gets initialized on every call!” and then I’d see it was in a static method and think “…well, the compiler must surely optimize this. It’s a local member of a static method so that’s fine.” Wrong.

The following – option C in our quiz – is no faster that option A.

//C
static void Method_C()
{
    Regex x = new Regex("somepattern");
    x.IsMatch("test.string!");
}

What about the static method Regex.IsMatch()?

There’s a static IsMatch() method on the Regex class that can be called as a quick an easy way to evaluate an expression. My understanding is that this is defined just like option C, but by my measurements can perform up to twice as fast. In fact, Regex.IsMatch() – option B – performs at about the same speed as option D under my testing scenario.

//B
void Method_B()
{
    Regex.IsMatch("test.string!", "somepattern");
}

I’ll have to investigate this further.

Compile vs not compile

The final question is whether you should initialize your regular expression object using RegexOptions.Compiled. This generally depends. A compiled Regex gives about 30% better runtime performance but can take as much as ten times longer to initialize.

With an ASP.NET app, I’d say the answer is pretty clear in most cases: go with the compiled version (on a static Regex object!). The BCL team states “…the bottom line is that you should only use this mode for a finite set of expressions which you know will be used repeatedly” which is the case in most of the regular expressions I come across in an ASP.NET application. You’re mileage may vary, of course.

Option E, when ignoring the increased startup cost, is the fastest of all the options presented.

//E
static readonly Regex regexForMethod_E = new Regex("somepattern", RegexOptions.Compiled);
public void Method_E()
{
    regexForMethod_E.IsMatch("test.string!");
}  

The verdict

Ignoring initialization time, here are the results of the quiz – where each method was executed 10,000 times.

regex execution time comparison

Calling IsMatch() on the compiled static Regex was by far the fastest operation, and in my opinion, the best way to use a regular expression in an ASP.NET application provided it will be used often.

What about the initialization costs? It is definitely not trivial to use RegexOptions.Compiled!

regex startup times

But given this only has to happen once (and not 10,000 times!) for the life of an ASP.NET application, I’m willing to accept this startup cost for the comparatively smaller runtime performance increase of the non-compiled version.

Getting started with SQLite and .NET

SQLite is a “self-contained, serverless, zero-configuration, transactional SQL database engine.” It is utilized in a few systems you may have heard of: Firefox, Skype, iPhone, and Andriod to name a few. The entire database is stored in a single file, which means your application or website can utilize a fully functional relational database without the constraints or costs of a traditional database server.

So when you don’t want to shell out the cash for SQL Server, your host doesn’t offer MySQL, and you’re tired of dancing around XML files as a database alternative, you can turn to SQLite!

System.Data.SQLite

You can install and use the core SQLite library on the official download page, but as a .NET developer your best bet is go with System.Data.SQLite – an ADO.NET provider for the SQLite engine. It also includes design-time support in Visual Studio 2005/2008!

I’m going to demonstrate the full process of setup using a simple C# .NET console application:

Install System.Data.SQLite from sqlite.phxsoftware.com

Include Visual Studio support for the version(s) desired.

sqlite ado.net provider installer sqlite designer installation

Create a new application, reference System.Data.SQLite

I’ve created a simple console application.

add reference to system.data.sqlite System.Data.SQLite referenced

Create a new database

Go to the Server Explorer and add a new Connection. Select SQLite as the data source, and on the following screen click “New…” to specify the name and location of the database you wish to create. Click OK and you’ve just established your connection!

Note: there is no specific naming convention for the file extension, and in this case I did not provide a file extension at all. Using something like .sqlite, .db, or .sdb all make sense to me. SQLite Administrator (a freeware GUI tool) seems to expect .sdb as the default file extension, whereas SQLite Manager (a Firefox addon) looks for .sqlite files by default.

SQLite change data source SQLite add connection

Right click on the new connection and view properties to examine the connection string. In my case it is: data source="C:\path\to\my\project\SQLiteFun\SQLiteDb"

Add a new table

Expand the database connection and right-click “Add New Table.” The table designer is still in development, so it’s important to note that you don’t have to use Visual Studio as the GUI tool for the database. There are a number of 3rd party tools you can use, and I’ll mention a couple below.

SQLite add new table SQLite add new table pt2

I’ve created a table named “Colors” and filled it with some data just for this demonstration.

SQLite table retrieve data

Write some traditional ADO.NET code

The System.Data.SQLite namespace contains all the classes used below (SQLiteConnection, SQLiteCommand, SQLiteDataReader). Here I’m using the typical ADO.NET way of creating a connection, a command, and executing a datareader. The name and hex database fields are outputted to the console one record at a time.

static void Main(string[] args)
{
    string connStr = @"data source=""C:\path-to-my-project\SQLiteFun\SQLiteDb""";
    string sql = "select * from Colors";

    using (SQLiteConnection conn = new SQLiteConnection(connStr))
    {
        SQLiteCommand cmd = new SQLiteCommand(sql, conn);
        SQLiteDataReader rdr = null;
        conn.Open();
        try
        {
            rdr = cmd.ExecuteReader(CommandBehavior.CloseConnection);
            while (rdr.Read())
            {
                Console.WriteLine(rdr["name"] + " " + rdr["hex"]);
            }
        }
        finally
        {
            rdr.Close();
        }
    }

    Console.Read();
}

And the output:

program output

That’s it!

That’s all there is to get started with SQLite in .NET using System.Data.SQLite!

GUI Tools

There are a number of third party GUI tools to interact with your SQLite database (thus, installing and using Visual Studio design-time support is purely optional). Below are examples of two of them in use.

SQlite Administrator

SQLite Administrator is a great little freeware tool supporting multiple languages and many features.

SQLite Administrator GUI

Firefox plugin

SQLite Manager is a Firefox addon (or see project hosted on google code: http://code.google.com/p/sqlite-manager/)

SQLite Manager GUI

Next up: SQLite with ASP.NET

In the beginning of this article I alluded to the fact that you may choose to use SQLite as a free database alternative to a paid SQL Server (or other) host, but I’ve completely ignored ASP.NET in this article.

I’m going to tinker with SQLite some more, using it with ASP.NET both locally and on a shared hosting provider. The results I will leave for a follow-up article.