Querying SharePoint

Introduction

SharePoint, being a content management system, of course, offers a couple of ways to query its contents programmatically. Here we will explore some of these options.

Web Parts

First, of course, there are the web parts. These allow us to configure queries visually on a page. The most important web parts are:

ContentByQueryWebPart: use this for simple queries that do not return much contents, on a single site collection. Can be used in SharePoint Online. Can only be customized through XSLT.

ContentBySearchWebPart (introduced in SharePoint 2013): more powerful, but does not exist in SharePoint Online. Can handle more complex queries that can span multiple site collections and multiple levels of sorting. Can only be customized through HTML and JavaScript templates. Results can be refined.

XsltListViewWebPart/DataFormWebPart: can be used to view of a specific list. The display can be totally configured. XsltListViewWebPart is a bit more powerful.

ListViewByQuery: requires that you pass an SPList and a SPQuery instance. Can only display pre-defined views.

APIs

There are several APIs for querying, either directly or using the search index.

SPQuery: can only be applied to a single list:

var query = new SPQuery();

query.Query = "<Where><Eq><FieldRef Name='Title'/><Value Type='Text'>Bla Bla</Value></Eq></Where>";

 

var list = site.RootWeb.Lists["Some List"];

 

var table = list.GetItems(query).GetDataTable();

SPSiteDataQuery: can be applied to several lists across a site collection. Has some issues, for example, won’t return values for multi-value fields:

var query = new SPSiteDataQuery();

query.Lists = "<List Name='Tasks'/>";

query.Query = "<Where><Eq><FieldRef Name='Title'/><Value Type='Text'>Bla Bla</Value></Eq></Where>";

query.Webs = "<Web Scope='SiteCollection'/>";

 

var table = site.RootWeb.GetSiteData(query);

KeywordQuery: uses the search index to search for keywords, so it requires that contents are indexed beforehand, and the search service is functioning:

using (var query = new KeywordQuery(site))

{

    query.QueryText = "Bla Bla";

    query.ResultsProvider = SearchProvider.Default;

 

    var searchExecutor = new SearchExecutor();

 

    var resultTableCollection = searchExecutor.ExecuteQuery(query);

 

    var searchResult = resultTableCollection.Filter("TableType", KnownTableTypes.RelevantResults).Single();

 

    var table = new DataTable();

    table.TableName = "Result";

    table.Load(searchResult, LoadOption.OverwriteChanges);

}

FullTextSqlQuery: uses SharePoint Search SQL to execute queries, which makes it generally more powerful than KeywordQuery:

using (var query = new FullTextSqlQuery(site))

{

    query.QueryText = "SELECT * FROM scope() WHERE Title = 'Teste'";

    query.ResultsProvider = SearchProvider.Default;

 

    var searchExecutor = new SearchExecutor();

 

    var resultTableCollection = searchExecutor.ExecuteQuery(query);

 

    var searchResult = resultTableCollection.Filter("TableType", KnownTableTypes.RelevantResults).Single();

 

    var table = new DataTable();

    table.TableName = "Result";

    table.Load(searchResult, LoadOption.OverwriteChanges);

}

CrossListQueryInfo and CrossListQueryCache: performs queries in a single site collection but multiple sites, with optional audience targeting. CrossListQueryCache caches the results for a period of time:

var crossListQueryInfo = new CrossListQueryInfo();

crossListQueryInfo.Query = "<Where><Eq><FieldRef Name='Title'/><Value Type='Text'>Bla Bla</Value></Eq></Where>";

crossListQueryInfo.Lists = "<List Name='Some List'/>";

crossListQueryInfo.Webs = "<Webs Scope='SiteCollection' />";

crossListQueryInfo.UseCache = true;

 

var crossListQueryCache = new CrossListQueryCache(crossListQueryInfo);

 

var table = crossListQueryCache.GetSiteData(site.RootWeb);

Client KeywordQuery: this is the client counterpart to KeywordQuery. It uses the SharePoint Client Components, or Client Side Object Model (CSOM), which means, it accesses SharePoint through its web services. It is basically similar to the server KeywordQuery, but can be used from a remote machine:

var keywordQuery = new Microsoft.SharePoint.Client.Search.Query.KeywordQuery(ctx);

keywordQuery.QueryText = "SharePoint";

 

var searchExecutor = new Microsoft.SharePoint.Client.Search.Query.SearchExecutor(ctx);

 

var results = searchExecutor.ExecuteQuery(keywordQuery);

 

ctx.ExecuteQuery();

 

var searchResult = results.Value.Where(x => x.TableType == KnownTableTypes.RelevantResults.ToString()).Single();

Web Services

Search.asmx: SOAP web service that takes a SharePoint SQL query. Part of the SharePoint Foundation 2010 Web Services, now somewhat obsolete.

Lists.asmx: Another SOAP web service that can return and update items in a list.

ListData.svc: WCF Data Service REST/OData that can be used for querying (including OData queries) or modifying contents of lists.

SharePoint 2013 REST Services: new REST/OData web services introduced in SharePoint 2013. Includes _api/web, _api/search, _api/web/lists, for searches, web or list operations.

SharePoint Foundation RPC Protocol

The SharePoint Foundation RPC Protocol, now obsolete, this allowed querying, exporting contents and performing a number of other operations through the OWSSVR.DLL handler. Although almost unused nowadays, still offers the only out of the box way to, for example, export a list in XML format.

JavaScript

In SharePoint 2010 the JavaScript Side Object Model (JSOM) was introduced and in version 2013 it was enhanced. It is now possible to do anything that the SharePoint Client API allows.

Conclusion

You see, lots of ways to get contents from SharePoint, as usual. Make sure you chose the one that best suits your needs.

References

SharePoint 2013 .NET Server, CSOM, JSOM, and REST API index

When to use the Content Query Web Part or the Content Search Web Part in SharePoint

Choose the right API set in SharePoint 2013

Use OData query operations in SharePoint REST requests

SharePoint Server 2013 Client Components SDK

SharePoint Search SQL Syntax Reference

ASP.NET Web Forms Extensibility: Model Binding Value Providers

ASP.NET 4.5 introduced model binding: basically, it is a way for databound controls – Repeater, GridView, ListView, etc – to be fed, not from a datasource control – ObjectDataSource, EntityDataSource, SqlDataSource, etc -, but from a method in the page. This method needs to return a collection, and may have parameters. The problem is: how these parameters get their values? The answer is: through a model binding value provider.

A model binding value provider is a class that implements IValueProvider, and normally is injected through a ValueProviderSourceAttribute-derived attribute. ASP.NET includes some implementations:

If we want, say, to return a value from the Common Service Locator, it’s pretty easy. First, an attribute:

[Serializable]

[AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false)]

public sealed class ServiceLocatorAttribute : ValueProviderSourceAttribute

{

    private readonly Type serviceType;

    private readonly String key;


    public ServiceLocatorAttribute(Type serviceType, String key = null)

    {

        this.serviceType = serviceType;

        this.key = key;

    }


    public override IValueProvider GetValueProvider(ModelBindingExecutionContext modelBindingExecutionContext)

    {

        return new ServiceLocatorValueProvider(this.serviceType, this.key);

    }

}

And now the actual value provider:

public sealed class ServiceLocatorValueProvider : IValueProvider

{

    private readonly Type serviceType;

    private readonly String key;


    public ServiceLocatorValueProvider(Type serviceType, String key)

    {

        this.serviceType = serviceType;

        this.key = key;

    }


    public Boolean ContainsPrefix(String prefix)

    {

        return true;

    }


    public ValueProviderResult GetValue(String key)

    {

        return new ValueProviderResult(ServiceLocator.Current.GetInstance(this.serviceType, this.key), null, CultureInfo.CurrentCulture);

    }

}

You can even have the ServiceLocatorAttribute implement the IValueProvider interface, I just separated it because conceptually they are different things.

Finally, here’s how we would use it:

public IQueryable<SomeEntity> GetItems([ServiceLocator(typeof(MyComponent), "SomeKey")] MyComponent cmp)

{

    //do something

}

Pretty sleek, don’t you think? Winking smile

Visual Studio Tips

Update: see the second post here and the third here.

Some random tips:

  1. If you need to run a web site under a different domain, so as to test multitenancy, for example, you need to run Visual Studio as an Administrator, otherwise you will get an error about an invalid hostname;
  2. If you want, you can configure Visual Studio to always start as Administrator: set the compatibility options to require additional permissions, see more here;
  3. You can have the Solution Explorer track (select automatically) the file you are editing; just select option ToolsOptionsTrack Active Item in Projects and Solutions;
  4. In case you need to find some class that you don’t know where is located, or you only know a part of its name, use the EditNavigate To option or click <Ctrl>+<comma>;
  5. Split the editor window: select WindowSplit; to close it, unselect it;
  6. You can now move a window to another monitor;
  7. Select columns across lines: click <Alt> while you make a vertical selection using the mouse or cursor keys; you can then copy the selection or paste some code into it;
  8. With <Alt>+<Up> or <Alt>+<Down>, you can switch the order of lines;
  9. Paste your JSON or XML code as classes: select EditPaste SpecialPaste JSON as Classes/Paste XML as Classes;
  10. You can see the classes that inherit from some of your project’s class: just select the file containing it in Solution Explorer, expand the selection to find the class, and then expand the class; you will find an option Derived Types.

And that’s it for now. More will follow!

Java vs C# – Part 2

Introduction

This is part two of a series of posts on Java and C#. You can read the first part, on structure, here. This time, we are going to talk about a lot of things that weren’t covered before, and leave some stuff for future posts! Smile

Object and Collection Initialization

C# offers an interesting syntax for initializing instance properties at the same time a variable is declared, which can be combined with parameterized constructors:

MyClass c = new MyClass("constructor argument") { OneProperty = 1, AnotherProperty = "two" };

It also offers a syntax for defining the values of a collection upon declaration:

List<string> list = new List<string>{ "A", "B", "C" };

Dictionary<int, string> dictionary = new Dictionary<int, string>{ { 0, "A" }, { 1, "B" } };

Any class with an instance Add method can use this syntax, because it’s this method that the compiler calls behind the scene. Inside the { }, we need to pass as many elements as the Add method takes, and of the same type.

Casts

In Java, we only have one kind of cast between types:

Object o = ...;

String s = (String) o;

But in C#, we have two: the same as in Java, plus a “dynamic”, that returns null if the types are not compatible:

Object o = 1;

String s = o as String; //s is null

The as operator can only be used with reference types (classes and interfaces) and nullable types (like int ?). It does not automatically use conversion operators (see below).

In C# there’s also something related, the null coalescing operator. Basically, it allows this syntax for initializing a variable to some value only if it is null:

Object o1 = null;

Object o2 = new MyClass();

Object o3 = o1 ?? o2; //short for: o1 == null ? o3 : o1

Methods

Undefined Number of Parameters

Both Java and C# support methods with an undefined number of parameters. The syntax is slightly different, in C# being:

public void Print(params String [] args)

{

}

An in Java:

public void print(String... args)

{

}

Default Parameter Values

C# allows setting default parameter values. The default values can only be:

  • null;
  • Literals (“string”, 1, false, etc);
  • Enumerated values (MyEnum.Value);
  • Constant or read-only fields (MyClass. SomeField).
public void SayHello(String to = "me")

{

}

A method can have any number of parameters with default values, but these parameters need to come at the end, after any other parameters without default values. Java does not offer default parameter values, we have to use method overloading for that.

Changing Parameter Order

C#, unlike Java, also allows passing parameters in any order, by name, which is very useful when we have methods with a lot of parameters, and we don’t want to remember their exact order:

public void DoSomething(int a, string b)

{

}


DoSomething(b: "a string value", a: 10);

Passing Parameters by Reference

C# has two ways to pass parameters:

  • By value, the default, which is a pointer for reference types – classes and interfaces – and the actual value for value types – enumerations, structures;
  • By reference: the actual address of the variable is passed, similar to ** or & in C++.

Passing parameter values by reference can be done in one of two ways:

  • Forcing the parameter to have a value set;
  • Not forcing the parameter to have a value set.

One example that forces assignment uses the out keyword:

public void Execute(out int result)

{

    result = 0;

}

And if no assignment is required, we use ref instead:

public void Swap(ref int a, ref int b)

{

    int c = a;

    a = b;

    b = c;

}

Both out and ref are functionally equivalent, but out enforces a compile-time constraint that the parameter has a value set. Passing values by reference is particularly useful in the case of structures, because, since they are not passed by pointer, they need to be copied byte by byte, which can take some time, and they might also be boxed if the method argument is of a reference type; passing structures by reference only sends the address of the local variable.

By comparison, Java always passes parameters by value, meaning, basic types pass their actual bytes and the others are passed as pointers to the original variable.

Extension Methods

C# offers the concept of extension methods. An extension method appears to be part of some type, as an instance method of that type, but it doesn’t break encapsulation, because it really isn’t part of it, and it doesn’t have access to the type’s internals.

Extension methods are defined as static methods in static classes with a this parameter of the target type:

namespace Extensions

{

    public static class StringExtensions

    {

        public static String Revert(this String s)

        {

            //...

        }

    }

    }

We call an extension method just as we call a regular method, provided that the class that defines it is in context, either by being in the same namespace as the calling method’s class, or by having its namespace imported.

using Extensions;//this is where the StringExtensions class lives


//...


String text = "abcd";

String reverted = text.Revert();

Java has virtual extension methods, also called default methods, which provide a default implementation of a method in an interface, which is then inherited (and can be overridden) by classes implementing the interface. This is the building block for the Stream API introduced recently. I talked about default methods on the first part of this series, but here’s an example.

public interface MyInterface

{

    default void doSomething()

    {

        //do something

    }

}

Default methods are always public, so there’s no need to use the public qualifier.

Static Interface Methods

Java also allows defining static methods, with implementation, in interfaces:

public interface MyInterface

{

    static void doSomethingElse()

    {

        //does something else

    }

}

Like default methods, static interface methods are always public.

C# doesn’t have any way to add statics or code to interfaces.

Synchronized Methods

Both languages allow a method, static or instance, to be declared as synchronized, meaning, it will lock the object on which it is being called (or the class, if it is a static method). The Java syntax is:

public synchronized void myMethod()

{

    //I am synchronized

}

While the C# one use the MethodImplAttribute attribute:

[MethodImpl(MethodImplOptions.Synchronized)]

public void MyMethod()

{

    //I am synchronized

}

The syntax for acquiring a lock on an object is identical, but Java uses the synchronized keyword:

synchronized (this.someLock)

{

    //...

}

And C#, lock:

lock (this.someLock)

{

    //...

}

Inline Methods

In C#, it is possible to instruct the compiler to try to inline certain methods, through the MethodImplAttribute attribute:

public class Something

{

    [MethodImpl(MethodImplOptions.AggressiveInlining)]

    public void ShouldBeMadeInline()

    {

    }

}

The actual decision, however, is up to the compiler. Java does not allow this.

Operator Overloading

Overloadable Operators

In C#, most operators (arithmetic, comparison, bitwise) can be overloaded for a class, similarly to C++. This means that C# allows them to be redefined, so as to implement a more friendly syntax, or just change the default one:

public static bool operator == (MyClass c1, MyClass c2)

{

    return c1.MyProperty == c2.MyProperty;

}

In this example, I am changing the default == operator, which just does a reference comparison, to a value comparison, where the actual contents of the class are compared. If we change ==, we also need to change !=:

public static bool operator != (MyClass c1, MyClass c2)

{

    return !c1 == c2;

}

Some of the basic operators (+=, for example), cannot be defined explicitly, but can be defined from others (+):

public static MyClass operator + (MyClass c1, MyClass c2)

{

    return new MyClass(c1.MyProperty + c2.MyProperty);

}

It is also possible to compare unrelated classes, but the declaring class must appear as one of the arguments:

public static bool operator == (MyClass c, String s)

{

    return c.MyProperty == s;

}

The argument order defines if the operator is to be applied, for example, the previous code applies to:

MyClass c = new MyClass();

bool areEqual = c == "some string";

But not to:

MyClass c = new MyClass();

bool areEqual = "some string" == c;

We can, however, add two times the same overloadable operator with the arguments switched, so that they can be called interchangeably. The String class overrides the == operator, so as to always do comparisons by value.

The number of arguments is defined by the operator, there are unary and binary operators, and the types they return cannot be changed. For example, operator == always expects two arguments of any kind but has to return a bool.

Type Conversions

C# also features a special kind of operator: type conversion. Actually, there are two, for implicit and explicit conversions. Implicit conversions do not need an explicit cast:

public static implicit operator string (MyClass c)

{

    return c.MyProperty; //MyProperty is of type string

}


MyClass c = new MyClass();

string s = c;

Whereas explicit ones do:

public static explicit operator int (MyClass c)

{

    return int.Parse(c.Property); //MyProperty is of type string

}


MyClass c = new MyClass();

int s = (int) c;

All operators need to be public and static.

Attributes

Attributes are static metadata that can be added to types, packages, parameters, members, variables and assemblies (in C#). Some attributes have meaning to the compiler, and in C#, they can even be used as an Aspect-Oriented Programming (AOP) mechanism, because some system attributes are evaluated at runtime.

Java offers the following out of the box attributes (called annotations in Java):

There are also meta-annotations, annotations that apply to other annotations:

As you can see, an annotation starts with a @ and must be defined as an interface using a special syntax:

@Target(value=CLASS)

public @interface MyAnnotation

{

    String name() default "";

    int number();    //required since a default was not supplied

}

Annotation methods can only return basic types, enumerations and arrays of them, and cannot take parameters.

The application of the MyAnnotation annotation can be:

@MyAnnotation(number = 10) //uses default value for name

public class MyClass

{

}

In C#, attributes are not totally different, but there are some differences:

  • An attribute must inherit from the Attribute class, and, by convention, should have the Attribute suffix;
  • When applied, we can leave out the Attribute suffix;
  • Attribute’s members can only be of basic types, enumerations, or arrays of them;
  • Required attribute properties should be passed in the attribute’s constructor.

There are lots of attributes included in the .NET, so it is not practical to cover them all. I leave just some examples:

By applying an AttributeUsageAttribute, we can specify:

  • AllowMultiple: if there can be many occurrences of this attribute, in the same element;
  • Inherited: if the attribute’s presence and values is inherited in descending classes;
  • ValidOn: the elements to which the attribute can be applied (All, Assembly, Class, Constructor, Delegate, Enum, Event, Field, GenericParameter, Interface, Method, Module, Parameter, Property, ReturnValue, Struct).

Here’s an example of a C# attribute:

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct, Inherited = true, AllowMultiple = false)]

public class MyAttribute : Attribute

{

    public MyAttribute(String required)

    {

        this.Required = required;

    }


    public String Required { get; private set; }


    public Int32 Optional { get; set; }

}

And its usage, notice that we leave out the Attribute suffix and the declaration syntax:

[My("name", Optional = 10)]

public struct MyStruct

{

    //...

}

Exceptions

Throwable Types

In .NET, any type can be thrown as an exception, but C# limits this to instances of the Exception class, or one derived from it.

In Java, we can only throw classes that implement the Throwable interface. The most common example of one such class is Exception.

Checked Exceptions

In Java, methods in classes, enumerations and interfaces must declare any exceptions that they may throw, except those inheriting from RuntimeException; these are considered special, in that they can be thrown at unforeseen situations – a division by zero, a null pointer access, etc. The syntax is for declaring the “expectable” exceptions is:

public void myMethod() throws MyException

{

}

Calling any method that declares that it may throw an exception requires that the calling code be wrapped in a try…catch block, where all checked exception types must be explicitly handled, or, of course, a superclass of them (catch is polymorphic):

try

{

    myMethod();

}

catch (MyException ex)

{

}

In both languages, more specific exception classes need to be catched first, that is, if you want to catch an Exception and a MyException that inherits from Exception, the catch block for MyException must be the first. C# allows you to omit either the class variable or even the class, if it doesn’t matter:

try

{

    //...

}

catch(MyException)

{

    //no need to refer to the exception instance

    throw;  //no argument required

}

catch

{

    //all other exception types

}

Rethrowing Exceptions

In Java as in C#, we can rethrow an exception caught in a catch clause:

try

{

    //...

}

catch (Exception ex)

{

    throw ex;

}

However, if we do it like this in C#, we lose the stack trace prior to the method issuing the throw. If we don’t want that, the alternative syntax is:

try

{

    //...

}

catch (Exception ex)

{

    throw;

}

Notice that if we don’t pass an argument to throw, it will rethrow the current exception – of course, this only works inside a catch clause.

Iterations

In C# and in Java we can iterate through the elements of a collection using either iterators or a specific syntax, which for C# is:

foreach (String item in list)

{

    //...

}

And for Java:

for (String arg : args)

{

    //...

}

In C#, any collection that has a method GetEnumerator returning an IEnumerator can benefit of this syntax, normally, all collections inheriting from IEnumerable (non-generic) or IEnumerable<T>. Java has a similar requirement, but the method needs to be called iterator and the required interface is Iterator<T>, which is implemented by most collections.

Returning Enumerables

In C#, if we want to return enumerations of values from a method, we normally prototype the method as returning IEnumerable<T>. If we do, we have a simplified syntax for returning individual values from it:

public IEnumerable<String> GetPhrases()

{

    var count = 0;


    for (var s in listOfStrings)

    {

        if (++count == 0)

        {

            yield break;    //break loop

        }


        yield return s;    //return one value, but continue loop

    }

}

Lambda Functions

Lambda functions in C# are built upon delegates and extension methods. A lambda is just syntactic sugar for calling methods – which can be defined inline, as anonymous ones -, and are most useful in collections processing:

List<MyClass> untidyCollection = ...;

List<MyClass> sortedAndFilteredCollection = untidyCollection.Where(c => c.MyProperty > 100).OrderBy(c => c.MyProperty).ToList();

In this example, Where and OrderBy are lambda functions defined over the IEnumerable<T> interface, which is implemented by List<T>. The types of the lambda variables can be omitted. This would be the same as:

class MyClassComparer : IComparer<MyClass>

{

    public Int32 Compare(MyClass c1, MyClass c2)

    {

        return c1.MyProperty.Compare(c2.MyProperty);

    }

}


List<MyClass> FilterCollection(List<MyClass> source, Int32 value)

{

    List<MyClass> target = new List<MyClass>();


    foreach (MyClass c in source)

    {

        if (c.MyProperty > value)

        {

            target.Add(c);

        }

    }


    return target;

}


List<MyClass> SortCollection(List<MyClass> source)

{

    List<MyClass> target = new List<MyClass>(source);

    target.Sort(new MyClassComparer());

    return target;

}


List<MyClass> untidyCollection = ...;

List<MyClass> sortedAndFilteredCollection = SortCollection(FilterCollection(untidyCollection));

Uuuf… see the gain?

A lambda can have several parameters:

Func<MyClass, Int32, MyClass> multiplicationTransformation = (c, multiplier) => new MyClass(c.MyProperty * multiplier);

MyClass source = ...;

MyClass target = multiplicationTransformation(source, 10);

In Java, things are very different. First, a lambda function can only be used over a functional interface, that is, an interface implementation with a single method. A method call that takes as a single parameter a class that implements this functional interface can be made a lambda function:

interface Operation

{

    default int operate(int a, int b);

}


class Calculator

{

    int doOperation(Operation op, int a, int b)

    {

        return op.operate(a, b);

    }

}


Calculator calc = new Calculator();

Operation sumOperation = (int x, int y) -> x + y;

calculator.doOperation(sumOperation, 1, 2);

Also comparison:

List<MyClass> unsortedCollection = ...;

List<MyClass> sortedCollection = Collections.sort(unsortedCollection, (MyClass c1, MyClass c2) -> c1.getMyProperty().compareTo(c2.getMyProperty()));

And finally, action listeners:

JButton button = ...;

button.addActionListener(evt -> System.out.println("Button clicked"));

Expression Trees

Related, but even more interesting than lambda expressions, are expression trees. These can be defined using the same syntax as lambda expressions:

List<MyClass> untidyCollection = ...;

IQueryable<MyClass> untidyQueryable = untidyCollection.AsQueryable();

IQueryable<MyClass> sortedAndFilteredQueryable = untidyQueryable.Where(x => x.MyProperty > 100).OrderBy(x => x.MyProperty);

But now sortedAndFilteredQueryable is an IQueryable<T>, a standard interface for wrapping expressions that return something. From it we can access the underlying Expression, the base class for all expression

Expression expression = sortedAndFilteredQueryable.Expression;


if (expression is MethodCallExpression)

{

    MethodCallExpression methodCall = expression as MethodCallExpression;

    Method method = methodCall.Method;


    foreach (Expression arg in methodCall.Arguments)

    {

        //iterate through each argument

        if (arg is ConstantExpression)

        {

            //constant

        }

        else if (arg is MemberExpression)

        {

            //property or field

        }

    }

}

This capability to analyze at runtime an expression is the basis for, for example, translating expression trees to SQL or OData calls – Entity Framework, LINQ to SQL, NHibernate, WCF Data Services, all use expression trees. Unlike lambdas, which do not retain the expression used, just the result, expression trees do not execute, but instead describe a C# expression.

Auto Closing Blocks

Both Java and C# offer an interesting construct for making sure resources are released when they are no longer needed.

In C#, these resources must implement IDisposable, and the syntax for the using block is as this:

using (IDisposable ctx = new DisposableContext())

{

    //...

}

It allows multiple disposables in the same block:

using (var disp1 = new DisposableContext())

using (var disp2 = new DisposableContext())

{

    //...

}


In Java, the required interface is AutoCloseable and the feature is called try with resources:

try (AutoCloseable disp1 = new Something())

{

    //...

}

The syntax for having several auto-closing variables is also allowed:

try (AutoCloseable disp1 = new DisposableContext(), AutoCloseable disp2 = new DisposableContext())

{

    //...

}

This basically is the same as (in both languages):

MyClass c = new MyClass();


try

{

    //...

}

finally

{

    if (c != null)

    {

        c.Dispose();    //C#

        c.close();      //Java

    }

}

Conclusion

Well, not exactly a conclusion! There will be more posts, keep dropping by and sending your feedback! Winking smile

Again, I need to thank Roberto Cortez (@radcortez) for his review of the Java parts! Thanks, man! Winking smile

Entity Framework Code First Succinctly, Second Edition

It’s now official: I will be working on a new, updated edition, of my Entity Framework Code First Succinctly, that I wrote for Syncfusion’s Succinctly series.

The first edition was about Entity Framework 5, and a lot has happened since. I would like to ask all of my blog readers that have read Entity Framework Code First Succinctly and are into Entity Framework Code First to send me your comments, corrections or suggestions for the new edition. I will be very thankful!

Hosting HTTP Resources

Introduction

How do I host thee? Let me count the ways!

You may not have realized that .NET offers a lot of alternatives when it comes to hosting an HTTP server, that is, without resorting to IIS, IIS Express or the now gone Visual Studio Web Development Server (aka, Cassini, rest in peace); by that, I either mean:

  • Opening up a TCP port and listening for HTTP requests, or a subset of them;
  • Running ASP.NET pages without a server.

In this post I am going through some of them. Some are specific to web services, but since they understand REST, I think they qualify as well as generic HTTP hosting mechanisms.

.NET HttpListener

Let’s start with HttpListener. This is included in .NET since version 2 and offers a decent server for static contents, that is, it cannot run any dynamic contents, like ASP.NET handlers, nor does it know anything about them. You merely point it to a physical folder on your file system, and it will happily serve any contents located inside it. Let’s see an example:

using (var listener = new System.Net.HttpListener())

{

    var url = "http://*:2000/";

    listener.Prefixes.Add(url);

    listener.Start();

 

    var ctx = listener.GetContext();

 

    var message = "Hello, World!";

 

    ctx.Response.StatusCode = (Int32) HttpStatusCode.OK;

    ctx.Response.ContentType = "text/plain";

    ctx.Response.ContentLength64 = message.Length;

 

    using (var writer = new StreamWriter(ctx.Response.OutputStream))

    {

        writer.Write(message);

    }

 

    Console.ReadLine();

}

This is a very basic example that just listens on port 2000, for any host name and request, and just returns Hello, World! when contacted before shutting down.

ASP.NET ApplicationHost

Complementary to HttpListener, we have a way to execute ASP.NET handlers (ASPX pages, ASHX generic handlers and ASMX web services) in a self-hosted application domain. For that, we use the ApplicationHost class to create the ASP.NET application domain, and a regular .NET class for the server implementation. An example:

public class Host : MarshalByRefObject

{

    public void ProcessPage(String page, String query, TextWriter writer)

    {

        var worker = new SimpleWorkerRequest(page, query, writer);

        HttpRuntime.ProcessRequest(worker);

    }

}

 

//strip out bin\debug, so as to find the base path where web files are located

var path = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location).Replace(@"\bin\Debug", String.Empty);

 

//we need to copy the assembly to the base path

File.Copy(Assembly.GetExecutingAssembly().Location, Path.Combine(path, "bin", Assembly.GetExecutingAssembly().CodeBase.Split('/').Last()), true);

 

var host = System.Web.Hosting.ApplicationHost.CreateApplicationHost(typeof(Host), "/", path) as Host;

host.ProcessPage("Default.aspx", null);

Notice the File.Copy call; this is necessary because the assembly referenced by the Default.aspx page needs to be located in the same folder as the page. An alternative to this would be to add a post build-event to the Visual Studio project:

image

I leave as an exercise to the interested readers how we can combine this with HttpListener! Winking smile

OWIN WebApp

Moving on to more recent technologies, we now have OWIN. In case you’ve been living in another world and haven’t heard of OWIN, I’ll just say that it is a standard for decoupling .NET from any particular web servers, like IIS or IIS Express. It also happens to have a self-hosting implementation – which, by the way, uses HttpListener underneath.

We need to add a reference to the Microsoft.Owin.SelfHost NuGet package:

image

After that, we just register an instance of WebApp with the default parameters, add an handler, and we’re done:

class Program

{

    public static void Configuration(IAppBuilder app)

    {

        app.Use(new Func<AppFunc, AppFunc>(next => (async ctx =>

        {

            using (var writer = new StreamWriter(ctx["owin.ResponseBody"] as Stream))

            {

                await writer.WriteAsync("Hello, World!");

            }

        })));

    }

 

    static void Main(String[] args)

    {

        using (WebApp.Start<Program>("http://*:2000"))

        {

            Console.ReadLine();

        }

    }

}

Again, no fancy dynamic stuff, just plain and simple HTTP: it waits for a request and just returns Hello, World!. It is possible to run ASP.NET MVC on top of OWIN, that is the goal of project Helios, which is currently in alpha stage. Do check out the Helios NuGet package at https://www.nuget.org/packages/Microsoft.Owin.Host.IIS/1.0.0-alpha1:

image

WCF ServiceHost

Since its release, WCF offers a way for it to be self-hosted in a .NET process. The class responsible for that is ServiceHost, or one of its descendants, like WebServiceHost, more suitable for REST. I will show an example using REST, which can be easily tested using a web browser:

[ServiceContract]

public interface IRest

{

    [WebGet(ResponseFormat = WebMessageFormat.Json)]

    [OperationContract]

    String Index();

}

 

public class Rest : IRest

{

    public String Index()

    {

        return "Hello, World!";

    }

}

 

using (var host = new WebServiceHost(typeof(Rest)))

{

    var url = new Uri(@"http://localhost:2000");

    var binding = new WebHttpBinding();

 

    host.AddServiceEndpoint(typeof(IRest), binding, url);

    host.Open();

 

    Console.ReadLine();

}

This example listens for a request of /Index on port 2000 and upon receiving it, returns Hello, World! in JSON format – because we are only sending a string, it will be wrapped in . WCF REST out of the box only supports returning data in XML or JSON format, no Text or HTML, but, to be fair, that’s not what it was meant to. Should be possible to return HTML, but, honestly, it would probably mean more work than it’s worth.

Web API HttpServer

Another web services technology in the .NET stack is Web API. Web API uses a concept similar to MVC, with controllers, models and action methods, but no views. It can be self-hosted as well, using the HttpServer class. In order to use it, install the Microsoft.AspNet.WebApi.SelfHost NuGet package. You will notice that its description claims that it is legacy, and has been replaced for another based on OWIN, yet, it is fully functional, if you don’t required it to be OWIN-compliant:

image

Because of the Web API architecture, we need to implement a controller for handling requests, :

public class DummyController : ApiController

{

    [HttpGet]

    public IHttpActionResult Index()

    {

        return this.Content(HttpStatusCode.OK, "Hello, World!");

    }

}

In this example, we do not take any parameters and just return the usual response.

Here’s the infrastructure code:

var url = "http://localhost:2000";

var config = new HttpSelfHostConfiguration(url);

config.Routes.MapHttpRoute("DefaultApi", "api/{controller}/{action}");

 

using (var server = new HttpSelfHostServer(config))

{

    server.OpenAsync().Wait();

}

The DummyController is found by reflecting the current executing assembly and applying conventions; any HTTP requests for /api/Dummy/Index will land there and the outcome will be plain text.

IIS Hostable Web Core

Now, this one is tricky. IIS, from version 7, allows hosting its core engine in-process, that is, from inside another application; this is called IIS Hostable Web Core (HWC). We can supply our own Web.config and ApplicationHost.config files and specify a root folder from which IIS will serve our web resources, including any dynamic contents that IIS can serve (ASPX pages, ASHX handlers, ASMX and WCF web services, etc). Yes, I know, this contradicts my introduction, where I claimed that this post would be about hosting web resources without IIS… still, I think this is important to know, because it can be fully controlled through code.

You need to make sure HWC is installed… one option is using PowerShell’s Install-WindowsFeature cmdlet:

Or the Server Manager application:

 

Features page

 

Because HWC is controlled through an unmanaged DLL, we have to import its public API control functions and call it with .NET code. Here’s an example:

public class Host : IDisposable

{

    private static readonly String FrameworkDirectory = RuntimeEnvironment.GetRuntimeDirectory();

    private static readonly String RootWebConfigPath = Environment.ExpandEnvironmentVariables(Path.Combine(FrameworkDirectory, @"Config\Web.config"));

 

    public Host(String physicalPath, Int32 port)

    {

        this.ApplicationHostConfigurationPath = Path.Combine(Path.GetTempPath(), Path.GetTempFileName() + ".config");

        this.PhysicalPath = physicalPath;

        this.Port = port;

 

        var applicationHostConfigurationContent = File.ReadAllText("ApplicationHost.config");

        var text = String.Format(applicationHostConfigurationContent, this.PhysicalPath, this.Port);

 

        File.WriteAllText(this.ApplicationHostConfigurationPath, text);

    }

 

    ~Host()

    {

        this.Dispose(false);

    }

 

    public String ApplicationHostConfigurationPath

    {

        get;

        private set;

    }

 

    public Int32 Port

    {

        get;

        private set;

    }

 

    public String PhysicalPath

    {

        get;

        private set;

    }

 

    public void Dispose()

    {

        this.Dispose(true);

        GC.SuppressFinalize(this);

    }

 

    protected virtual void Dispose(Boolean disposing)

    {

        this.Stop();

    }

 

    public void Start()

    {

        if (IisHostableWebCoreEngine.IsActivated == false)

        {

            IisHostableWebCoreEngine.Activate(this.ApplicationHostConfigurationPath, RootWebConfigPath, Guid.NewGuid().ToString());

        }

    }

 

    public void Stop()

    {

        if (IisHostableWebCoreEngine.IsActivated == true)

        {

            IisHostableWebCoreEngine.Shutdown(false);

 

            this.PhysicalPath = String.Empty;

            this.Port = 0;

 

            File.Delete(this.ApplicationHostConfigurationPath);

 

            this.ApplicationHostConfigurationPath = String.Empty;

        }

    }

 

    private static class IisHostableWebCoreEngine

    {

        private delegate Int32 FnWebCoreActivate([In, MarshalAs(UnmanagedType.LPWStr)] String appHostConfig, [In, MarshalAs(UnmanagedType.LPWStr)] String rootWebConfig, [In, MarshalAs(UnmanagedType.LPWStr)] String instanceName);

        private delegate Int32 FnWebCoreShutdown(Boolean immediate);

 

        private const String HostableWebCorePath = @"%WinDir%\System32\InetSrv\HWebCore.dll";

        private static readonly IntPtr HostableWebCoreLibrary = LoadLibrary(Environment.ExpandEnvironmentVariables(HostableWebCorePath));

 

        private static readonly IntPtr WebCoreActivateAddress = GetProcAddress(HostableWebCoreLibrary, "WebCoreActivate");

        private static readonly FnWebCoreActivate WebCoreActivate = Marshal.GetDelegateForFunctionPointer(WebCoreActivateAddress, typeof(FnWebCoreActivate)) as FnWebCoreActivate;

 

        private static readonly IntPtr WebCoreShutdownAddress = GetProcAddress(HostableWebCoreLibrary, "WebCoreShutdown");

        private static readonly FnWebCoreShutdown WebCoreShutdown = Marshal.GetDelegateForFunctionPointer(WebCoreShutdownAddress, typeof(FnWebCoreShutdown)) as FnWebCoreShutdown;

 

        internal static Boolean IsActivated

        {

            get;

            private set;

        }

 

        internal static void Activate(String appHostConfig, String rootWebConfig, String instanceName)

        {

            var result = WebCoreActivate(appHostConfig, rootWebConfig, instanceName);

 

            if (result != 0)

            {

                Marshal.ThrowExceptionForHR(result);

            }

 

            IsActivated = true;

        }

 

        internal static void Shutdown(Boolean immediate)

        {

            if (IsActivated == true)

            {

                WebCoreShutdown(immediate);

                IsActivated = false;

            }

        }

 

        [DllImport("Kernel32.dll")]

        private static extern IntPtr LoadLibrary(String dllname);

 

        [DllImport("Kernel32.dll")]

        private static extern IntPtr GetProcAddress(IntPtr hModule, String procname);

    }

}

In order for this to work, we need to have an ApplicationHost.config file, a minimum working example being:

<?xml version="1.0" encoding="UTF-8" ?>

<configuration>

    <configSections>

        <sectionGroup name="system.applicationHost">

            <section name="applicationPools" />

            <section name="sites" />

        </sectionGroup>

 

        <sectionGroup name="system.webServer">

            <section name="globalModules" />

            <section name="modules" />

            <section name="handlers" />

            <section name="staticContent" />

            <section name="serverRuntime" />

            <sectionGroup name="security">

                <section name="access"/>

                <sectionGroup name="authentication">

                    <section name="anonymousAuthentication" />

                    <section name="windowsAuthentication" />

                    <section name="basicAuthentication" />

                </sectionGroup>

                <section name="authorization" />

                <section name="requestFiltering" />

                <section name="applicationDependencies" />

                <section name="ipSecurity" />

            </sectionGroup>

            <section name="asp" />

            <section name="caching" />

            <section name="cgi" />

            <section name="defaultDocument" />

            <section name="directoryBrowse" />

            <section name="httpErrors" />

            <section name="httpLogging" />

            <section name="httpProtocol" />

            <section name="httpRedirect" />

            <section name="httpTracing" />

            <section name="isapiFilters" allowDefinition="MachineToApplication" />

            <section name="odbcLogging" />

        </sectionGroup>

    </configSections>

 

    <system.applicationHost>

        <applicationPools>

            <add name="AppPool" managedPipelineMode="Integrated" managedRuntimeVersion="v4.0" autoStart="true" />

        </applicationPools>

 

        <sites>

            <site name="MySite" id="1">

                <bindings>

                    <binding protocol="http" bindingInformation="*:{1}:localhost" />

                </bindings>

                <application path="/" applicationPool="AppPool" >

                    <virtualDirectory path="/" physicalPath="{0}" />

                </application>

            </site>

        </sites>

    </system.applicationHost>

 

    <system.webServer>

        <globalModules>

            <add name="StaticFileModule" image="%windir%\System32\inetsrv\static.dll" />

            <add name="AnonymousAuthenticationModule" image="%windir%\System32\inetsrv\authanon.dll" />

            <add name="ManagedEngine" image="%windir%\Microsoft.NET\Framework\v4.0.30319\webengine4.dll" />

        </globalModules>

 

        <modules>

            <add name="StaticFileModule" />

            <add name="AnonymousAuthenticationModule" />

            <add name="DefaultAuthentication" type="System.Web.Security.DefaultAuthenticationModule" preCondition="managedHandler" />

            <add name="UrlAuthorization" type="System.Web.Security.UrlAuthorizationModule" preCondition="managedHandler" />

            <add name="FileAuthorization" type="System.Web.Security.FileAuthorizationModule" preCondition="managedHandler" />

            <add name="AnonymousIdentification" type="System.Web.Security.AnonymousIdentificationModule" preCondition="managedHandler" />

        </modules>

 

        <handlers accessPolicy="Read, Script">

            <add name="PageHandlerFactory-Integrated" path="*.aspx" verb="GET,HEAD,POST,DEBUG" type="System.Web.UI.PageHandlerFactory" preCondition="integratedMode" />

            <add name="StaticFile" path="*" verb="*" modules="StaticFileModule" resourceType="Either" requireAccess="Read" />

        </handlers>

 

        <staticContent>

            <mimeMap fileExtension=".html" mimeType="text/html" />

            <mimeMap fileExtension=".jpg" mimeType="image/jpeg" />

            <mimeMap fileExtension=".gif" mimeType="image/gif" />

            <mimeMap fileExtension=".png" mimeType="image/png" />

        </staticContent>

    </system.webServer>

</configuration>

And all we need to start hosting pages on the port and physical path specified by ApplicationHost.config is:

using (var host = new Host(path, port))

{

    host.Start();

 

    Console.ReadLine();

}

A couple of notes:

  • Because it calls unmanaged functions, can be terrible to debug;
  • The ApplicationHost.config needs to be in the application’s binary build directory and must have two placeholders, {0} and {1}, for the physical path and HTTP port, respectively;
  • It refers to .NET 4.0, if you want to change it, you will to change a number of modules and paths;
  • Only very few modules are loaded, if you want, get a full file from %HOMEPATH%\Documents\IISExpress\config\ApplicationHost.config and adapt it to your likings.

.NET TcpListener

And finally, one for the low-level guys. The TcpListener class allows the opening of TCP/IP ports and the handling of requests coming through them. It doesn’t know anything about the HTTP protocol, of course, so, if we want to leverage it, we need to implement it ourselves. Here’s a very, very, basic example:

var listener = System.Net.Sockets.TcpListener.Create(2000);

listener.Start();

 

using (var client = listener.AcceptTcpClient())

{

    using (var reader = new StreamReader(client.GetStream()))

    using (var writer = new StreamWriter(client.GetStream()))

    {

        var request = reader.ReadLine();

 

        writer.WriteLine("HTTP/1.1 200 OK");

        writer.WriteLine("Content-type: text/plain");

        writer.WriteLine();

        writer.WriteLine("Hello, World!");

        writer.Flush();

    }

}

 

listener.Stop();

Here we’re just reading any string content and responding with some HTTP headers plus the usual response. Of course, HTTP is quite complex, so I wouldn’t recommend you try to implement it yourself.

Conclusion

I presented a couple of solutions for hosting web resources, servicing HTTP requests or running ASP.NET handlers. Hopefully you will find one that matches your needs.

Entity Framework Extensibility Index

Updated on March 10th.

Here you will find a list of all my posts on Entity Framework extensibility.

Freetext Extension in Entity Framework Code First

I posted before a solution for adding custom SQL functions to Entity Framework Code First as extension methods. This time I am going to show how we can do something similar for the FREETEXT function of SQL Server. Please note that this example will only work if you have the Fulltext Search component installed and your table is indexed.

OK, so we want to have an extension method like this:

[DbFunction("CodeFirstDatabaseSchema", "FREETEXT")]

public static Boolean Freetext(this String column, String value)

{

    return column.Contains(value);

}

In order for Entity Framework to recognize it, we need to write our own convention, this is because Entity Framework only recognizes out of the box a number of SQL Server built-in functions. We can write one as this:

public class FreetextConvention : IStoreModelConvention<EdmModel>

{

    public static readonly FreetextConvention Instance = new FreetextConvention();


    public void Apply(EdmModel item, DbModel model)

    {

        var valueParameter = FunctionParameter.Create("column", this.GetStorePrimitiveType(model, PrimitiveTypeKind.String), ParameterMode.In);

        var formatParameter = FunctionParameter.Create("value", this.GetStorePrimitiveType(model, PrimitiveTypeKind.String), ParameterMode.In);

        var returnValue = FunctionParameter.Create("result", this.GetStorePrimitiveType(model, PrimitiveTypeKind.Boolean), ParameterMode.ReturnValue);


        var function = this.CreateAndAddFunction(item, "FREETEXT", new[] { valueParameter, formatParameter }, new[] { returnValue });

    }


    protected EdmFunction CreateAndAddFunction(EdmModel item, String name, IList<FunctionParameter> parameters, IList<FunctionParameter> returnValues)

    {

        var payload = new EdmFunctionPayload { StoreFunctionName = name, Parameters = parameters, ReturnParameters = returnValues, Schema = this.GetDefaultSchema(item), IsBuiltIn = true };

        var function = EdmFunction.Create(name, this.GetDefaultNamespace(item), item.DataSpace, payload, null);


        item.AddItem(function);


        return (function);

    }


    protected EdmType GetStorePrimitiveType(DbModel model, PrimitiveTypeKind typeKind)

    {

        return (model.ProviderManifest.GetStoreType(TypeUsage.CreateDefaultTypeUsage(PrimitiveType.GetEdmPrimitiveType(typeKind))).EdmType);

    }


    protected String GetDefaultNamespace(EdmModel layerModel)

    {

        return (layerModel.GlobalItems.OfType<EdmType>().Select(t => t.NamespaceName).Distinct().Single());

    }


    protected String GetDefaultSchema(EdmModel layerModel)

    {

        return (layerModel.Container.EntitySets.Select(s => s.Schema).Distinct().SingleOrDefault());

    }

}

This registers a FREETEXT function with two string parameters and returning a boolean. All is fine, we add it to the DbContext in OnModelCreating:

modelBuilder.Conventions.Add(FreetextConvention.Instance);

You might have noticed the usage of a Instance static field, this is because, since the FreetextConvention class is stateless, there’s no point in creating many of them, we can just use the same instance.

Now, if we issue a LINQ query as:

var customers = ctx.Customers.Where(x => x.Name.Freetext("ricardo")).ToList();

It will fail miserably, complaining about this SQL fragment:

WHERE ((FREETEXT(name, N'ricardo') = 1)

The “= 1” part is here because the function is prototyped as boolean, which maps to SQL Server’s BIT data type, and the value for true is 1. Apparently, SQL Server does not support comparisons of some functions with 1; but if we run it as:

WHERE ((FREETEXT(name, N'ricardo'))

without the explicit comparison, it works perfectly. So, all we have to do is get rid of “= 1”. Fortunately, Entity Framework, as of version 6, offers some very nice extensibility points. There are at least two ways by which we can achieve this:

  • By intercepting the command tree;
  • By intercepting the raw SQL.

Here we will use option #2 and leave command trees for another post.

We need to identity something with a format of “FREETEXT(something) = 1”. We can do it using a regular expression, and the interception of the SQL command can be achieved by implementing IDbCommandInterceptor (no reference documentation yet, but I have reported it and it will soon be fixed, hopefully) and registering one such instance in the DbInterception (same) static class. An IDbCommandInterceptor implementation might look like this:

public class FreetextInterceptor : IDbCommandInterceptor

{

    public static readonly FreetextInterceptor Instance = new FreetextInterceptor();


    private static readonly Regex FreetextRegex = new Regex(@"FREETEXT\(([^)]+\))\) = 1");


    public void NonQueryExecuted(DbCommand command, DbCommandInterceptionContext<Int32> interceptionContext)

    {

    }


    public void NonQueryExecuting(DbCommand command, DbCommandInterceptionContext<Int32> interceptionContext)

    {

    }


    public void ReaderExecuted(DbCommand command, DbCommandInterceptionContext<DbDataReader> interceptionContext)

    {

    }


    public void ReaderExecuting(DbCommand command, DbCommandInterceptionContext<DbDataReader> interceptionContext)

    {

        var matches = FreetextRegex.Matches(command.CommandText);


        if (matches.Count > 0)

        {

            command.CommandText = FreetextRegex.Replace(command.CommandText, "FREETEXT($1)");

        }

    }


    public void ScalarExecuted(DbCommand command, DbCommandInterceptionContext<Object> interceptionContext)

    {

    }


    public void ScalarExecuting(DbCommand command, DbCommandInterceptionContext<Object> interceptionContext)

    {

    }

}

You can see that the only method we’re interested in is ReaderExecuting (again, no documentation available), with is the one that will be called just before a SQL SELECT query is sent to the database. In here we analyze the CommandText property of the DbCommand and get rid of the “= 1” clause, using a regular expression. Finally, we need to register the interceptor before we issue the query, maybe in the static constructor of our DbContext:

DbInterception.Add(FreetextInterceptor.Instance);

And now we can finally execute our query:

var customers = ctx.Customers.Where(x => x.Name.Freetext("ricardo")).ToList();

And that’s it. Don’t forget that in order for this to work, you need to enable Full Text Search.

ASP.NET Web Forms Extensibility: Control Builder Interceptors

After my previous post on Control Builders, what could possibly come next? Of course, Control Builder Interceptors! Not much documentation on this one, which is a shame, because it is an even more powerful feature that was recently introduced in ASP.NET 4.5.

A Control Builder Interceptor inherits from, unsurprisingly, ControlBuilderInterceptor. This is configured for the whole application, in the Web.config file, in the compilation section, by a controlBuilderInterceptorType (sorry, no link, since the ASP.NET 4.5 documentation is not online) attribute:

<compilation targetFramework="4.5" controlBuilderInterceptorType="MyNamespace.MyControlBuilderInterceptor, MyAssembly" />

Similarly to Control Builders, a Control Builder Interceptor allows us to:

Granted, less than Control Builders, but the point here is that this is fired for all markup-declared controls, not just those that have a specific Control Builder applied to. With that in mind, we can write code like this:

public class MyControlBuilderInterceptor : ControlBuilderInterceptor

{

    //raised for every control on markup

    public static event Action<ControlInterceptedEventArgs> ControlIntercepted;

 

    public override void OnProcessGeneratedCode(ControlBuilder controlBuilder, CodeCompileUnit codeCompileUnit, CodeTypeDeclaration baseType, CodeTypeDeclaration derivedType, CodeMemberMethod buildMethod, CodeMemberMethod dataBindingMethod, IDictionary additionalState)

    {

        var controlDeclaration = buildMethod.Statements[0] as CodeVariableDeclarationStatement;

 

        if (controlDeclaration != null)

        {

            var controlName = controlDeclaration.Name;

 

            buildMethod.Statements.Insert(buildMethod.Statements.Count - 1, new CodeSnippetStatement(String.Concat(this.GetType().FullName, ".Intercept(@", controlName, ");")));

        }

 

        base.OnProcessGeneratedCode(controlBuilder, codeCompileUnit, baseType, derivedType, buildMethod, dataBindingMethod, additionalState);

    }

 

    public override void PreControlBuilderInit(ControlBuilder controlBuilder, TemplateParser parser, ControlBuilder parentBuilder, Type type, String tagName, String id, IDictionary attributes, IDictionary additionalState)

    {

        if ((attributes != null) && (attributes.Contains("Text") == true))

        {

            //make property value uppercase

            attributes["Text"] = (attributes["Text"] as String).ToUpper();

        }

 

        base.PreControlBuilderInit(controlBuilder, parser, parentBuilder, type, tagName, id, attributes, additionalState);

    }

 

    public static void Intercept(Control instance)

    {

        var handler = ControlIntercepted;

 

        if (handler != null)

        {

            handler(new ControlInterceptedEventArgs(instance));

        }

    }

}

And there you have it. By adding an event handler to MyControlBuilderInterceptor.ControlIntercepted, we can analyze and change the properties of every control:

[Serializable]

public sealed class ControlInterceptedEventArgs : EventArgs

{

    public ControlInterceptedEventArgs(Control control)

    {

        this.Control = control;

    }

 

    public Control Control { get; private set; }

}

 

MyControlBuilderInterceptor.ControlIntercepted += e =>

{

    var myControl = e.Control as MyControl;

    

    if (myControl != null)

    {

        myControl.Text = myControl.Text.ToUpper();

    }

};

Stay tuned for more extensibility points of your favorite framework!

ASP.NET Web Forms Extensibility: Control Builders

One of the most often ignored extensibility point in Web Forms is the Control Builder. Control Builders are subclasses of ControlBuilder (or other more specialized, such as FileLevelPageControlBuilder, for pages, or FileLevelMasterPageControlBuilder, for master pages) that can be specified per class. It controls some aspects of a control instance:

It also allows overriding a couple of things:

  • The parameters specified in the markup (Init);
  • What to do when the control builder is added to a parent control builder (OnAppendToParentBuilder);
  • Modify the code that will be generated in the code-behind class that is produced by ASP.NET or the code that will be used to instantiate the control (ProcessGeneratedCode);
  • Change the tag’s inner textual content (SetTagInnerText);
  • Etc.

This is a powerful mechanism, which has even been used to allow generic control classes. We apply a control builder through a ControlBuilderAttribute (for regular controls) or FileLevelControlBuilderAttribute for pages, master pages or user controls.

I won’t go into many details, but instead I will focus on the Init and ProcessGeneratedCode methods.

Init let’s us do things such as:

public override void Init(TemplateParser parser, ControlBuilder parentBuilder, Type type, String tagName, String id, IDictionary attribs)

{

    if (type == typeof(SomeBaseControl)

    {

        //replace the control's type for another one

        type = typeof(SomeDerivedControl);

 

        //convert an hypothetical Text property value to upper case

        attribs["Text"] = (attribs["Text"] as String).ToUpper();

    }

 

    base.Init(parser, parentBuilder, type, tagName, id, attribs);

}

And ProcessGeneratedCode, messing with the generated page class:

public override void ProcessGeneratedCode(CodeCompileUnit codeCompileUnit, CodeTypeDeclaration baseType, CodeTypeDeclaration derivedType, CodeMemberMethod buildMethod, CodeMemberMethod dataBindingMethod)

{

    //add some interface to the generated page class

    derivedType.BaseTypes.Add(typeof(ISomeInterface));

 

    //add a property implementation to the generated page class

    var prop = new CodeMemberProperty();

    prop.Attributes = MemberAttributes.Public;

    prop.Name = "SomeProperty";

    prop.Type = new CodeTypeReference(typeof(String));    

    prop.GetStatements.Add(new CodeMethodReturnStatement(new CodePrimitiveExpression("Hello, World, from a generated property!")));

    

    derivedType.Members.Add(prop);

 

    base.ProcessGeneratedCode(codeCompileUnit, baseType, derivedType, buildMethod, dataBindingMethod);

}

But also something MUCH more fun! Imagine you are using an IoC container – I will use Unity, but you can use whatever you want. We might have something like this in Application_Start (or whatever method spawned from it);

var unity = new UnityContainer();

unity.RegisterInstance<MyControl>(new MyControl { Text = "Bla bla" });

ServiceLocator.SetLocatorProvider(() => new UnityServiceLocator(unity));

Notice I am using the Common Service Locator to abstract the IoC container and to make the code independent of it. Here, I am assigning a static instance to the MyControl type, in essence, a singleton.

Now, we can change our control builder so as to have the control build method return this instance:

public override void ProcessGeneratedCode(CodeCompileUnit codeCompileUnit, CodeTypeDeclaration baseType, CodeTypeDeclaration derivedType, CodeMemberMethod buildMethod, CodeMemberMethod dataBindingMethod)

{

    //return ServiceLocator.Current.GetInstance(typeof(MyControl));

    var type = Type.GetType((buildMethod.Statements[0] as CodeVariableDeclarationStatement).Type.BaseType);

    var currentProperty = new CodePropertyReferenceExpression(new CodeTypeReferenceExpression(typeof (ServiceLocator)), "Current");

    var getInstance = new CodeMethodInvokeExpression(currentProperty, "GetInstance", new CodeTypeOfExpression(type));

    var @cast = new CodeCastExpression(type, getInstance);

    var @return = new CodeMethodReturnStatement(@cast);

 

    buildMethod.Statements.Clear();

    buildMethod.Statements.Add(@return);

 

    base.ProcessGeneratedCode(codeCompileUnit, baseType, derivedType, buildMethod, dataBindingMethod);

}

In case you didn’t notice, what this does is, every time the MyControl control is instantiated in a page, for every request, ASP.NET will always return the same instance!

Now, I am not saying that you SHOULD do this, but only that you CAN do this! Winking smile

Take care out there…