Richard Banks was kind enough to interview me on Episode 8 of Talking Shop Down Under.
If you’re interested in some of the ideas behind the new Autofac 2.1 release, be sure to check out the podcast!
Posts by Nicholas Blumhardt
Introducing Autofac 2.1 RTW
After nearly two years of experimentation, design and development, Autofac’s second major release is here!
Autofac 2.1 is still the IoC container you know and love, but reorganised so that Autofac 1.4′s strengths — especially in providing a low-friction developer experience — really shine.
You can download the binaries here, or read on for some of the feature highlights.
Component Discovery
Otherwise known as convention-driven registration or scanning, Autofac 2 can register a set of types from an assembly according to user-specified rules:
var dataAccess = Assembly.GetExecutingAssembly();
builder.RegisterAssemblyTypes(dataAccess)
.Where(t => t.Name.EndsWith("Repository"))
.AsImplementedInterfaces();
builder.RegisterAssemblyTypes(dataAccess)
.Where(t => t.Name.EndsWith("Repository"))
.AsImplementedInterfaces();
The registration syntax for RegisterAssemblyTypes() is a superset of the registration syntax for single types, so methods like As<T>() all work with assemblies as well, and there’s very little extra API to learn.
Relationship Types
When working with IoC you frequently hear advice against passing the container around or resolving components from it directly. Where dynamic relationships are concerned, for example deferred creation, selection from alternatives or parameterisation, there has historically been very little guidance on the alternatives.
Autofac addresses this by automatically supporting small, focused, strongly-typed wrappers that express dynamic dependencies.
For example, instead of calling IContainer.Resolve<IDownloader>(), a WebCrawler component that needs to create instances of a downloader on-the-fly can take a dependency on Func<IDownloader> and the container will provide it automatically so long as IDownloader is registered.
class WebCrawler : IWebCrawler
{
Func<Uri, IDownloader> _downloaderFactory;
public WebCrawler (Func<Uri, IDownloader> downloaderFactory)
{
_downloaderFactory = downloaderFactory;
}
public void Crawl()
{
var downloader = _downloaderFactory(new Uri("http://autofac.org"));
foreach (var link in downloader.OutboundLinks)
// ...
}
}
{
Func<Uri, IDownloader> _downloaderFactory;
public WebCrawler (Func<Uri, IDownloader> downloaderFactory)
{
_downloaderFactory = downloaderFactory;
}
public void Crawl()
{
var downloader = _downloaderFactory(new Uri("http://autofac.org"));
foreach (var link in downloader.OutboundLinks)
// ...
}
}
As the example shows, you can pass parameters (in this case a Uri) that will be forwarded to the target component’s constructor.
Autofac 2 supports an extensive vocabulary of relationship types that the container understands and provides automatically based on the other available components.
| Relationship | Adapter Type | Meaning |
|---|---|---|
| A needs a B | None | Dependency |
| A needs a B at some point in the future | Lazy<B> |
Delayed instantiation |
| A needs a B until some point in the future | Owned<B> |
Controlled lifetime |
| A needs to create instances of B | Func<B> |
Dynamic instantiation |
| A provides parameters of types X and Y to B | Func<X,Y,B> |
Parameterisation |
| A needs all the kinds of B | IEnumerable<B> |
Enumeration |
| A needs to know X about B before using it | Meta<T> and Meta<B,X> |
Metadata interrogation |
For more information on relationship types, see the introductory article.
Component Metadata
If you’re familiar with the Managed Extensibility Framework (MEF) you have probably seen examples using component metadata.
Autofac uses the underlying support in .NET 4.0 to provide similar functionality. Metadata is associated with a component either in code:
builder.Register(c => new ScreenAppender())
.As<ILogAppender>()
.WithMetadata("AppenderName", "screen");
.As<ILogAppender>()
.WithMetadata("AppenderName", "screen");
Or in XML:
<component
type="MyApp.Components.Logging.ScreenAppender, MyApp"
service="MyApp.Services.Logging.ILogAppender, MyApp" >
<metadata>
<item name="AppenderName" value="screen" type="System.String" />
</metadata>
</component>
type="MyApp.Components.Logging.ScreenAppender, MyApp"
service="MyApp.Services.Logging.ILogAppender, MyApp" >
<metadata>
<item name="AppenderName" value="screen" type="System.String" />
</metadata>
</component>
Unlike a regular property, a metadata item can be queried and used without requiring an instance of the component to be created.
This makes it useful when selecting one of many components based on runtime criteria; or, where the metadata isn’t intrinsic to the component implementation. Metadata could represent the time that an ITask should run, or the button caption for an ICommand.
Other components can consume metadata using the System.Lazy<T,TMetadata> type.
public class Log
{
readonly IEnumerable<Lazy<ILogAppender, ILogAppenderMetadata>> _appenders;
public Log(IEnumerable<Lazy<ILogAppender, ILogAppenderMetadata>> appenders)
{
_appenders = appenders;
}
public void Write(string destination, string message)
{
var appender = _appenders.First(a => a.Metadata.AppenderName == destination);
appender.Value.Write(message);
}
}
{
readonly IEnumerable<Lazy<ILogAppender, ILogAppenderMetadata>> _appenders;
public Log(IEnumerable<Lazy<ILogAppender, ILogAppenderMetadata>> appenders)
{
_appenders = appenders;
}
public void Write(string destination, string message)
{
var appender = _appenders.First(a => a.Metadata.AppenderName == destination);
appender.Value.Write(message);
}
}
In .NET 3.5 (as well as 4.0) Autofac 2 provides the weakly typed Meta<T> class for consuming metadata as a dictionary.
Managed Extensibilty Framework Integration
MEF introduces a standard API for creating extensible applications in .NET 4.0. If your Autofac-based application has extensibility points, plugin developers can use the MEF attributes to mark up their extensions, while internally they can be hosted in the Autofac container just like any other Autofac component.
Any MEF catalog type can be registered directly with the container, so to use MEF’s directory scanning ability for example, a System.ComponentModel.Composition.DirectoryCatalog can be used.
var catalog = new DirectoryCatalog("Extensions");
builder.RegisterComposablePartCatalog(catalog);
builder.RegisterComposablePartCatalog(catalog);
For documentation on this API see the Autofac MEF integration wiki page.
There’s a deeper discussion of the underlying architecture here.
Other Improvements
Although Autofac 2 introduces some new features, a lot more work went into making the core architecture and API of Autofac more consistent, robust and explicit.
To list a very small selection:
- Generic type constraints are now respected – Autofac won’t try to use unsuitable generic types when resolving references to generic services.
- The instance parameters to activation events are strongly-typed, for example
builder.RegisterType<Foo>().OnActivating(e => e.Instance.Start()). - ASP.NET MVC controller registration is more flexible and simpler via the
RegisterControllers()method. - Non-shared (‘factory’) scope is the default, rather than Singleton.
- “Resolve Anything” support
- API documentation is seachable on Google.
Upgrading from Autofac 1.4
If you’re upgrading from an earlier Autofac release, see the New in V2 wiki page for more detailed information.
There are many breaking changes for users of Autofac 1.4 who want to upgrade. Most of these are just name changes, but some less commonly-used features will cause non-trivial rework. This is the price of keeping Autofac clean, supportable and relevant – if you’re affected by breaking changes you can find consolation in knowing that Autofac is not on the path to becoming a legacy framework 
.
If things do get tough, help is only ever an email away.
Where to Next?
The 2.1 release is largely foundational — its focus is on improving the core container. There are plenty of new features in it, but next in the pipeline is a 2.2 version including, for example, broader ASP.NET MVC support and no doubt some fixes and improvements based on learnings from 2.1.
Acknowledgements and Thanks
Autofac 2 draws on many inspirations and input from a large community. Direct credit for Autofac 2 belongs to the project members, contributors to the mailing list, and supporters in the blogosphere, on stackoverflow and on Twitter.
Many of the ideas in Autofac 2, just as with the version before it, derive from other projects like Windsor, MEF, Funq, Unity, Ninject, StructureMap and their precursors.
Extra thanks is due to the MEF team, whose tireless work is making the .NET a friendlier place for IoC every day.
The Must-Have Tablet for 2010
Quartet Cube
If you’re a fan of index cards or Post-it notes for work item tracking, here’s another simple helper you might enjoy.
The Quartet Cube is a tiny, portable metallic whiteboard.
On our recent project we’ve kept three in the project room and found them perfect for:
- Taking notes during meetings
- Small focused to-do lists (we often use a pink one to track things we’d like to refactor)
- Sketching ideas
- Communicating designs (as demonstrated in the photo by the remarkable Steven Nagy)
The added portability makes it easy to take one to your desk – or to somebody else’s.
Autofac 2.1 goes RC (the “me too!” release)
Today brings a new build of Autofac, now designated “Release Candidate”.
Autofac 2.1.9 includes the last of the critical changes for a full release. Since 2.1.8:
- Many bug fixes and small usability enhancements
BeginLifetimeScope()now allows additional components to be configured for the child scope- An AutofacContrib build for both .NET 3.5 and 4.0 is available (AutofacContrib.DynamicProxy2 not yet included)
- Two new adapters for the zoo:
Indexed<TKey,TValue>for dictionary-like dependenciesMeta<T>for un-typed metadata, available on .NET 3.5
- API documentation can be viewed online at api.autofac.org (this reflects the .NET 3.5-compatible version.)
Autofac 2.1 RC is now the recommended version for new projects. Please bear with us while the wiki is updated to reflect the new API.
Many thanks are due to the contributors and user community who have made this release possible, as well as my teammates at Readify who have put up with a bombardment of Autofac 2 material in the last few months
Get the downloads for .NET 3.5 and .NET 4.0 here.
The Relationship Zoo
Dependency Injection, unsurprisingly, is all about the relationships between components.
Components rarely exist or perform any useful task alone. A system that achieves a business function may use tens, hundreds or even thousands of different components, all working in collaboration to get a job done.
Early IoC containers understood one kind of relationship: “A needs a B.”
interface B { }
class A
{
public A(B b) { ... }
}
class A
{
public A(B b) { ... }
}
More complex relationships, like “A creates instances of B” required the author of component A to deal directly with the container to get things done, by calling container.Resolve<B>(), for example.
Since a majority of relationships are, in fact, simple direct dependencies, this was an acceptable point from which to start developing IoC containers as a technology. Recently, more powerful, declarative ways of specifying “higher-order” dependencies have emerged. In this article we’ll look at a selection of them, using Autofac 2 as an example implementation.
I was first introduced to the term “higher-order dependencies” by Mircea Trofin at Microsoft. I’m not sure I’m using it here in precisely the same sense. The .NET Composition Primitives, which Mircea was instrumental in creating, have some elegant mechanisms for handling them – in a future article I hope to cover this in more detail.
A Catalog of Relationships
It turns out that there are a lot of different ways that one component may relate to another.
Here’s a partial list to fill in the question mark above:
- A needs a B
- A needs a B at some point in the future
- A needs a B until some point in the future
-
A needs to create instances of B
- and provides parameters of types X and Y
- A needs all the kinds of B
- A needs to know X about B before using it
- …
This list is chosen carefully, because each of these relationships can be expressed declaratively through simple adapter types.
| Relationship | Adapter Type | Meaning |
|---|---|---|
| A needs a B | None | Dependency |
| A needs a B at some point in the future | Lazy<B> |
Delayed instantiation |
| A needs a B until some point in the future | Owned<B> |
Controlled lifetime |
| A needs to create instances of B | Func<B> |
Dynamic instantiation |
| A provides parameters of types X and Y to B | Func<X,Y,B> |
Parameterisation |
| A needs all the kinds of B | IEnumerable<B> |
Enumeration |
| A needs to know X about B before using it | Meta<B,X> |
Metadata interrogation |
Some of the types above will be familiar: Lazy<T>, Func<T> and IEnumerable<T> are all .NET BCL types, and are used here with their standard semantics.
Owned<T> and Meta<T> are introduced by Autofac, and fill some of the gaps in the BCL. They’re very simple types that could be replicated in an application that wanted to use them independently.
Lazy<T>
A lazy dependency is not instantiated until its first use. This appears where the dependency is infrequently used, or expensive to construct.
class A
{
Lazy<B> _b;
public A(Lazy<B> b) { _b = b }
public void M()
{
// The component implementing B is created the
// first time M() is called
_b.Value.DoSomething();
}
}
{
Lazy<B> _b;
public A(Lazy<B> b) { _b = b }
public void M()
{
// The component implementing B is created the
// first time M() is called
_b.Value.DoSomething();
}
}
Owned<T>
An owned dependency can be released by the owner when it is no longer required. Owned dependencies usually correspond to some unit of work performed by the dependent component.
class A
{
Owned<B> _b;
public A(Owned<B> b) { _b = b }
public void M()
{
// _b is used for some task
_b.Value.DoSomething();
// Here _b is no longer needed, so
// it is released
_b.Dispose();
}
}
{
Owned<B> _b;
public A(Owned<B> b) { _b = b }
public void M()
{
// _b is used for some task
_b.Value.DoSomething();
// Here _b is no longer needed, so
// it is released
_b.Dispose();
}
}
In an IoC container, there’s often a subtle difference between releasing and disposing a component: releasing an owned component goes further than disposing the component itself. Any of the dependencies of the component will also be disposed. Releasing a shared component is usually a no-op, as other components will continue to use its services.
Func<T> and Func<X,Y,T>
The ‘factory’ adapters imply creation of individual instances of the dependency. The parameterised versions allow initialisation data to be passed to the implementing component.
class A
{
Func<int, string, B> _b;
public A(Func<int, string, B> b) { _b = b }
public void M()
{
var b = _b(42, "http://hel.owr.ld");
b.DoSomething();
}
}
{
Func<int, string, B> _b;
public A(Func<int, string, B> b) { _b = b }
public void M()
{
var b = _b(42, "http://hel.owr.ld");
b.DoSomething();
}
}
IEnumerable<T>
Dependencies of an enumerable type provide multiple implementations of the same service (interface).
class A
{
IEnumerable<B> _bs;
public A(IEnumerable<B> bs) { _bs = bs }
public void M()
{
foreach (var b in bs)
b.DoSomething();
}
}
{
IEnumerable<B> _bs;
public A(IEnumerable<B> bs) { _bs = bs }
public void M()
{
foreach (var b in bs)
b.DoSomething();
}
}
Meta<T,M>
Metadata is data-about-data. Requesting metadata with a dependency allows the dependent component to get infomation about the provider of a service without invoking it.
class A
{
Meta<B,BMetadata> _b;
public A(Meta<B,BMetadata> b) { _b = b }
public void M()
{
if (_b.Metadata.SomeValue == "yes")
_b.Value.DoSomething();
}
}
{
Meta<B,BMetadata> _b;
public A(Meta<B,BMetadata> b) { _b = b }
public void M()
{
if (_b.Metadata.SomeValue == "yes")
_b.Value.DoSomething();
}
}
The Relationship Zoo
If you’ve read this far, you’re probably desperate for an example that doesn’t use the components A and B. I feel your pain! The truth is, while these dependencies are useful in their own right, really interesting dependencies often combine multiple adapters!
Choosing a File Viewer
Metadata is excellent when there are multiple implementations of a service, and one must be selected to perform a task. The selection criterion mightn’t be inherent in the component itself, so properties make awkward choices for representing this data.
Let’s say we have a number of file viewers, and, via configuration, we associate each viewer with the file types that it should be used to view.
interface IViewer
{
void View(string filename);
}
interface IViewerMetadata
{
IEnumerable<string> FileTypes { get; }
}
class Browser
{
IEnumerable<Meta<IViewer, IViewerMetadata>> _viewers;
public Browser(IEnumerable<Meta<IViewer, IViewerMetadata>> viewers)
{
_viewers = viewers;
}
public void OnViewFile(string filename)
{
var ext = Path.GetExtension(filename);
var viewer = _viewers.Single(v => v.Metadata.FileTypes.Contains(ext));
viewer.Value.View(filename);
}
}
{
void View(string filename);
}
interface IViewerMetadata
{
IEnumerable<string> FileTypes { get; }
}
class Browser
{
IEnumerable<Meta<IViewer, IViewerMetadata>> _viewers;
public Browser(IEnumerable<Meta<IViewer, IViewerMetadata>> viewers)
{
_viewers = viewers;
}
public void OnViewFile(string filename)
{
var ext = Path.GetExtension(filename);
var viewer = _viewers.Single(v => v.Metadata.FileTypes.Contains(ext));
viewer.Value.View(filename);
}
}
In this example, IEnumerable<T> and Meta<T> are combined to express the two features of the relationship between Browser and IViewer.
Mixing in dynamic creation, controlled lifetime or lazy initialization would often also make sense in this kind of scenario.
You can see how metadata is associated with an Autofac component here, or examine one of the many examples based on the MEF APIs here.
Creating and Releasing a Message Handler
Another common combination is that of dynamic instantiation and ownership of the instances. A message pump may create, use, then release a handler for each incoming message:
interface IMessageHandler
{
void Handle(Message message);
}
class MessagePump
{
Func<Owned<IMessageHandler>> _handlerFactory;
public MessagePump(Func<Owned<IMessageHandler>> handlerFactory)
{
_handlerFactory = handlerFactory;
}
public void Go()
{
while(true)
{
var message = NextMessage();
using (var handler = _handlerFactory())
{
handler.Value.Handle(message);
}
}
}
}
{
void Handle(Message message);
}
class MessagePump
{
Func<Owned<IMessageHandler>> _handlerFactory;
public MessagePump(Func<Owned<IMessageHandler>> handlerFactory)
{
_handlerFactory = handlerFactory;
}
public void Go()
{
while(true)
{
var message = NextMessage();
using (var handler = _handlerFactory())
{
handler.Value.Handle(message);
}
}
}
}
Many instances, with dynamic creation and controlled lifetime and parameters and and and whoah!
Yes, IEnumerable<Meta<Func<X,Y,Owned<T>>,M>> is in fact a valid relationship type. Glad you asked?
Common combinations can be eaiser to work with when they are baked into a single class. In MEF, for example, Meta<Lazy<T>> is represented as Lazy<T,M>. Likewise Func<Owned<T>> is represented as PartCreator<T>. You can plug these composite adapter types into Autofac via a custom registration source if you need them.
Custom delegate types can also ease angle-bracket-eyestrain if you use the parameterised factories a lot.
The core of Autofac 2 doesn’t have any special knowledge of any of these adapter types. They’re all plugged in as IRegistrationSource implementations, meaning that you are free to change or extend the set of adapter types as your needs dictate.
Muahahahahhahahaahhh!!!!
I heard that maniac laugh just then! Let me just slip in the disclaimer now: just because you can model almost any conceivable relationship type this way, doesn’t mean that you should. Where a simple direct dependency will suffice, don’t gouge out your eyes on six layers of nested angle brackets, or invest in new adapter types. Like all sharp tools, use context adapters with discretion.
At the same time, there’s practically no excuse to use IContainer or IComponentContext in your components anymore.
Conclusions and a Suggestion
You might not be using Autofac today, and might not have any desire to. That’s okay! Anything new and useful you see here will no doubt make its way back into the container you prefer – this is the magic of being part of an Open Source community.
If you do use Autofac, or are curious, download the .NET 4.0 version from the project site.
A note to container developers…
Although this is an Autofac-centric article, it draws on the combined experience of many passionate people who are driving .NET composition technology forward.
I’m not sure yet that we share a common vision of the “v.Next” IoC container – one thing we do seem to agree on is that it is harmful to have the container abstraction leak through into components. Perhaps in the future, IoC containers will be completely transparent, but we have some way yet to go.
Common Service Locator (CSL) was a step forward in interoperability. A good range of applications and frameworks that need dynamic or lazy instantiation no longer have to depend on a specific IoC container; I think this is one way we’ve maintained diversity and a healthy ecosystem.
CSL is a stopgap though – a service locator that could handle all of the scenarios above would be a monster of an interface indeed! CSL also breaks the declarative nature of components that use it.
I’d be very interested to hear thoughts on a new project, Common Context Adapters, which would include types like Owned<T> and Meta<T,M> to fill gaps in the BCL while it evolves. It would also provide baseline documentation on how wiring of Func<T> etc. should work.
Common Context Adapters would play a similar role to CSL by isolating applications and frameworks from the specifics of an IoC container, but in a way that is compatible with declarative dependency wiring and inversion of control.
I’m prepared to put effort into making this happen if there is enough interest.
Building an External DSL in C#
Download the example as a VS2010 solution.
Our current project includes a small workflow for submission and approval of user account creation requests. This makes a good example to discuss domain-specific languages and Sprache, so I’ll paraphrase some of the requirements here.
The set of user account types is open-ended; currently “employee”, “contractor”, “temporary” and so on. To request a particular kind of account, a user must fill in a questionnaire associated with that account type.
In the data collection and approval parts of the system, the content of the questionnaire is irrelevant so long as the necessary information is recorded and presented to the administrator, who will ultimately approve or decline the request.
The Challenge
Much of the system design is driven by the fact that the set of possible account types (and thus different questionnaires) is open. Creating new questionnaires should be possible without redeploying the application. Furthermore, the content of a particular questionnaire needs to be easily extended and modified, possibly by end-users themselves.
There are many possible ways to represent the questionnaires:
- Map a questionnaire domain model to relational database tables
- Create an XML-based questionnaire format
- Use Windows Workflow Foundation with loose XAML files
- Read the questionnaires from CSV files or spreadsheets
Each has its pros and cons with regard to ease of implementation, maintainability, user-friendliness and flexibility.
In this article, we’ll examine another appealing option: building a user-friendly mini-language to represent questionnaires.
Questionnaire Definition Language
You may have read some discussion of the differences between internal and external DSLs.
An internal DSL is a specially-constructed API in a general-purpose language like C# that, when used, reads more like a definition of the problem than a program to solve it.
An external DSL is a standalone language that must be parsed from source text before a program can work with it. Importantly for this example, an external DSL encourages a minimum of syntactic noise, and can be read without any program compilation.
The example questionnaire DSL looks like:
identification "Personal Details"
[
name "Full Name"
department "Department"
]
employment "Current Employer"
[
name "Your Employer"
contact "Contact Number"
#months "Total Months Employed"
]
[
name "Full Name"
department "Department"
]
employment "Current Employer"
[
name "Your Employer"
contact "Contact Number"
#months "Total Months Employed"
]
Above is a two-step questionnaire that collects personal and employment details.
- Each section has an id, a title, and a list of questions.
- Each question has an id and some prompting text.
- The declaration of a question id (e.g. #months) can be prefixed with a symbol to indicate what kind of data is being collected – the pound sign/hash in this case denotes a natural number.
The application will read the questionnaire definition associated with a particular kind of account request, and present the steps to the user in a wizard-like interface.
Approaches to Parsing the Questionnaire Definitions
Parsing is the process of taking text in a source language, like the questionnaire above, and converting it into a representation – usually some kind of object model – that a program can work with. For the C# programmer, there are several ways to achieve this.
Hand-built Parsers
The very simplest as well as the most complex parsers are often built by hand. The simple ones because the solution is readily evident to the programmer (e.g. “split the string by finding commas in a loop”) and the most complex because the programmer needs an extreme level of control (e.g. the C# compiler.) Parsing anything in between by hand is usually more trouble than it is worth, unless you’re really into languages and know what you’re doing (that definitely rules me out!)
Regular Expressions
These are a convenient way of matching and extracting patterns from text. .NET includes the built-in System.Text.Regex class for working efficiently with regular expressions, so they’re usually the first option to consider when faced with a parsing task. Beyond quite simple grammars, regular expressions rapidly become hard to read and maintain. This is perhaps the biggest of their shortcomings, but there are also many grammars that regular expressions are unable to parse (starting with those that allow nesting.)
Parser Construction Toolkits
Industrial-strength parser construction toolkits and ‘language workbenches’ allow a grammar to be specified in a declarative format. The toolkit includes build-time tools to generate classes in the target programming language (e.g. C#) that can parse the grammar. Using such a toolkit requires an investment in both learning how the toolkit works, and integrating it into a project’s build process. For small parsing tasks this can be overkill, but for anything of significant complexity or requiring high parsing throughput, learning and using to use such a toolkit is highly recommended.
Parser Combinators
This function-based technique is often used by default in functional languages like Haskell and F#, both of which have high-quality parser combinator libraries. C# also has a fledgling combinator library called Sprache, built by yours truly and used in the rest of the article. Sprache makes it very easy to write and maintain simple parsers, without a steep learning curve or build-time tasks. It fits very nicely with a test-driven development process. The drawbacks are currently speed, efficiency and sometimes the quality of error messages – none of which is a big deal when parsing simple DSLs. [Edit: since this article was written, parsing speed and error handling in Sprache have been significantly improved.]
Getting Started
First, download Sprache.dll. This article is organised in such a way that you should be able to follow along with the text by creating and testing parsers in Visual Studio with NUnit or similar.
Grammars are built from the bottom up. First, parsers are created for the low-level syntax elements like identifiers, strings and numbers. We then work upwards, combining these basic units into more complex ones until we have the complete language.
Parsing an Identifier
In our questionnaire definition language, the most-nested significant element is the question:
name "Full Name"
The basic parts here are an identifier an some quoted text. The first task for our parser will be to parse the identifier, in this case ‘name’.
[Test]
public void AnIdentifierIsASequenceOfCharacters()
{
var input = "name";
var id = QuestionnaireGrammar.Identifier.Parse(input);
Assert.AreEqual("name", id);
}
public void AnIdentifierIsASequenceOfCharacters()
{
var input = "name";
var id = QuestionnaireGrammar.Identifier.Parse(input);
Assert.AreEqual("name", id);
}
Parsers in Sprache are static methods on a class representing the grammar. QuestionnaireGrammar.Identifier is of type Parser<string>, i.e. it returns values of type string from the input.
The definition of the parser is:
public static readonly Parser<string> Identifier = Parse.Letter.AtLeastOnce().Text().Token();
This reads fairly well – we’re going to parse a non-empty sequence of letters and return the text representation of those letters. The elements of the parser here are:
Parse.Letter – the Sprache Parse class contains helper methods and properties for common parsing tasks. Letter is a simple parser of type Parser<char>, that reads a letter from the input and returns it as a char. If the next character on the input isn’t a letter, this parser won’t match.
AtLeastOnce() – all parsers created by Sprache support repetition this way. AtLeastOnce() takes a parser for a single element of type T and returns a new parser that will parse a sequence of elements, returning IEnumerable<T>.
Text() – the AtLeastOnce() modifier took our Parser<char> and converted it into a parser of type Parser<IEnumerable<char>>. The Text() helper function takes a parser of IEnumerable<char> and converts it into a Parser<string>, so that the result is more convenient to work with.
Token() – finally, the token modifier accepts then discards leading and trailing whitespace.
Simple?
There are a couple more tests we might be interested in for the Identifier parser.
[Test]
public void AnIdentifierDoesNotIncludeSpace()
{
var input = "a b";
var parsed = QuestionnaireGrammar.Identifier.Parse(input);
Assert.AreEqual(“a”, parsed);
}
public void AnIdentifierDoesNotIncludeSpace()
{
var input = "a b";
var parsed = QuestionnaireGrammar.Identifier.Parse(input);
Assert.AreEqual(“a”, parsed);
}
A Sprache parser will parse as much as it can before returning. In this test case the parser will succeed, but won’t consume all of the input. (Later we’ll see how to make assertions about end-of-input.)
[Test]
public void AnIdentifierCannotStartWithQuote()
{
var input = "\"name";
Assert.Throws<ParseException>(() => QuestionnaireGrammar.Identifier.Parse(input));
}
public void AnIdentifierCannotStartWithQuote()
{
var input = "\"name";
Assert.Throws<ParseException>(() => QuestionnaireGrammar.Identifier.Parse(input));
}
The Parse() extension method throws ParseException when the parser doesn’t match. You can alternatively use the non-throwing TryParse().
Once we’re happy that identifiers are being parsed correctly we can move on.
Parsing Quoted Text
Quoted text isn’t much harder to parse than an identifier – our basic version doesn’t support escaped characters or anything fancy.
Looking again at the input:
name "Full Name"
To parse the quoted text, we need to match:
- The opening quote
- Anything except another quote
- The closing quote
The quotes themselves aren’t particularly interesting to the program, so we’ll return only the text between them.
One test for the parser will look like:
[Test]
public void QuotedTextReturnsAValueBetweenQuotes()
{
var input = "\"this is text\"";
var content = QuestionnaireGrammar.QuotedText.Parse(input);
Assert.AreEqual("this is text", content);
}
public void QuotedTextReturnsAValueBetweenQuotes()
{
var input = "\"this is text\"";
var content = QuestionnaireGrammar.QuotedText.Parse(input);
Assert.AreEqual("this is text", content);
}
Jumping straight to the parser:
public static readonly Parser<string> QuotedText =
(from open in Parse.Char('"')
from content in Parse.CharExcept('"').Many().Text()
from close in Parse.Char('"')
select content).Token();
(from open in Parse.Char('"')
from content in Parse.CharExcept('"').Many().Text()
from close in Parse.Char('"')
select content).Token();
This opportunistic repurposing of the Linq query comprehension syntax was first described (AFAIK) by Luke Hoban from the F# team. The from clauses lay out the individual units of the syntax, while the select clause transforms them into the return value of the overall parser.
Parsing the Question
You’ve probably noticed by now that parsers are strongly-typed: a parser for a character returns char, and a parser for text returns string. A parser for a question, will return – Question!
public class Question
{
public Question(string id, string prompt)
{
Id = id;
Prompt = prompt;
}
public string Id { get; private set; }
public string Prompt { get; private set; }
}
{
public Question(string id, string prompt)
{
Id = id;
Prompt = prompt;
}
public string Id { get; private set; }
public string Prompt { get; private set; }
}
This is a great strength of combinator-based parsing when constructing DSLs. Once a semantic model for the problem has been built, the parser can translate input directly into it.
public static readonly Parser<Question> Question =
from id in Identifier
from prompt in QuotedText
select new Question(id, prompt);
from id in Identifier
from prompt in QuotedText
select new Question(id, prompt);
A unit test for a basic question now passes:
[Test]
public void AQuestionIsAnIdentifierFollowedByAPrompt()
{
var input = "name \"Full Name\"";
var question = QuestionnaireGrammar.Parse(input);
Assert.AreEqual("name", question.Id);
Assert.AreEqual("Full Name", question.Prompt);
}
public void AQuestionIsAnIdentifierFollowedByAPrompt()
{
var input = "name \"Full Name\"";
var question = QuestionnaireGrammar.Parse(input);
Assert.AreEqual("name", question.Id);
Assert.AreEqual("Full Name", question.Prompt);
}
Parsing a Section
Parsing a section is just like parsing a question: first we build the semantic model, then use the existing parsers to translate the source text.
Remember a section looks like:
identification "Personal Details"
[
name "Full Name"
department "Department"
]
[
name "Full Name"
department "Department"
]
We can represent this in the object model as:
public class Section
{
public Section(string id, string title, IEnumerable<Question> questions)
{
Id = id;
Title = title;
Questions = questions;
}
public string Id { get; private set; }
public string Prompt { get; private set; }
public IEnumerable<Question> Questions { get; private set; }
}
{
public Section(string id, string title, IEnumerable<Question> questions)
{
Id = id;
Title = title;
Questions = questions;
}
public string Id { get; private set; }
public string Prompt { get; private set; }
public IEnumerable<Question> Questions { get; private set; }
}
Building a parser is as easy as building the object model:
public static readonly Parser<Section> Section =
from id in Identifier
from title in QuotedText
from lbracket in Parse.Char('[').Token()
from questions in Question.Many()
from rbracket in Parse.Char(']').Token()
select new Section(id, title, questions);
from id in Identifier
from title in QuotedText
from lbracket in Parse.Char('[').Token()
from questions in Question.Many()
from rbracket in Parse.Char(']').Token()
select new Section(id, title, questions);
To complete the example, we have one more model class to define:
public class Questionnaire
{
public Questionnaire(IEnumerable<Section> sections)
{
Sections = sections;
}
public IEnumerable<Section> Sections { get; private set; }
}
{
public Questionnaire(IEnumerable<Section> sections)
{
Sections = sections;
}
public IEnumerable<Section> Sections { get; private set; }
}
Its corresponding parser (this time without the comprehension syntax):
public static Parser<Questionnaire> Questionnaire =
Section.Many().Select(sections => new Questionnaire(sections)).End();
Section.Many().Select(sections => new Questionnaire(sections)).End();
By affixing .End() to the parser, we require that the full input is parsed (i.e. there’s no trailing garbage.)
That’s all we need for the example without any data type qualifiers.
Supporting Answer Data Types
The finishing touches of our grammar add support for the answer type qualifiers.
#months "Total Months Employed"
We can use an enumeration for the possible answer types.
public enum AnswerType
{
Natural,
Number,
Date,
YesNo
}
{
Natural,
Number,
Date,
YesNo
}
This is a pretty limited set, so by brute force we’ll check for each possible qualifier.
public static Parser<AnswerType> AnswerTypeIndicator =
Parse.Char('#').Return(AnswerType.Natural)
.Or(Parse.Char('$').Return(AnswerType.Number))
.Or(Parse.Char('%').Return(AnswerType.Date))
.Or(Parse.Char('?').Return(AnswerType.YesNo));
Parse.Char('#').Return(AnswerType.Natural)
.Or(Parse.Char('$').Return(AnswerType.Number))
.Or(Parse.Char('%').Return(AnswerType.Date))
.Or(Parse.Char('?').Return(AnswerType.YesNo));
The Question object is modified to accept an AnswerType as a constructor parameter, and a simple modification of the Question parser completes our work.
public static Parser<Question> Question =
from at in AnswerTypeIndicator.Or(Parse.Return(AnswerType.Text))
from id in Identifier
from prompt in QuotedText
select new Question(id, prompt, at);
from at in AnswerTypeIndicator.Or(Parse.Return(AnswerType.Text))
from id in Identifier
from prompt in QuotedText
select new Question(id, prompt, at);
Summary
The complete parser is just six rules, totaling about 25 nicely-formatted lines of code.
While robust parsing is a non-trivial task in the real world, I hope this article shows that there are simple, low-friction options that fill some of the gaps between regular expressions and language workbenches.
MVC Integration Changes in Autofac Beta 2.1.6
Autofac 1.4 and earlier 2.1 versions used AutofacControllerModule as a way of finding and registering ASP.NET MVC controllers with the container.
In the Autofac 2.1 MVC integration, there is a new ContainerBuilder extension method called RegisterControllers.
var builder = new ContainerBuilder();
// Was:
// builder.RegisterModule(new AutofacControllerModule(...))
builder.RegisterControllers(Assembly.GetExecutingAssembly());
_containerProvider = new ContainerProvider(builder.Build());
ControllerBuilder.Current.SetControllerFactory(
new AutofacControllerFactory(_containerProvider));
// Was:
// builder.RegisterModule(new AutofacControllerModule(...))
builder.RegisterControllers(Assembly.GetExecutingAssembly());
_containerProvider = new ContainerProvider(builder.Build());
ControllerBuilder.Current.SetControllerFactory(
new AutofacControllerFactory(_containerProvider));
The reason for the switch is that RegisterControllers is a thin wrapper around the new assembly scanner, and supports the same syntax as the rest of Autofac’s registration methods:
builder.RegisterControllers(assembly)
.InjectProperties()
.OnActivated(e => Log.Information("Controller created: " + e.Instance));
.InjectProperties()
.OnActivated(e => Log.Information("Controller created: " + e.Instance));
Resolve Anything
Ward Bell, one of the most diligently pragmatic programmers out there, just wrote about bootstrapping Prism with containers other than Unity.
One of the pain points that Ward observes is Prism’s use of “resolve anything” – a Unity feature that causes the container to act as though all concrete types are registered.
// Works, even though Foo isn't registered,
// because Foo is concrete.
var container = new UnityContainer();
var foo = container.Resolve<Foo>();
// because Foo is concrete.
var container = new UnityContainer();
var foo = container.Resolve<Foo>();
Other containers have different behaivours – by default, Autofac will throw ComponentNotRegisteredException in this case.
I’m not a fan of Unity’s behaviour – I rarely use concrete types as services, and generally would want to configure them first anyway.
However, for those with different views, there are simple ways to make this work with Autofac.
Autofac 1.4 – RegisterTypesMatching()
Autofac 1.4 includes a configuration method that can help here. The parameter is a predicate on a requested Type, and if the result is true the container will happily resolve instances of the type.
var builder = new ContainerBuilder();
builder.RegisterTypesMatching(t => t.IsClass && !t.IsAbstract);
var container = builder.Build();
// Now works
var foo = container.Resolve<Foo>();
builder.RegisterTypesMatching(t => t.IsClass && !t.IsAbstract);
var container = builder.Build();
// Now works
var foo = container.Resolve<Foo>();
Autofac 2.1 – ResolveAnythingSource
Autofac 2 doesn’t have an equivalent to RegisterTypesMatching(). This is because Autofac 2′s assembly scanner, RegisterAssemblyTypes() does a much better job in similar scenarios.
Those who’ve been following along with this blog lately will have seen how registration sources provide a simple way to extend the container to understand new component types (like Lazy Dependencies.)
Well, the registration source to implement “resolve anything” is just a few lines, included here in its entirety. If you need this behaviour, feel free to include it in your project.
class ResolveAnythingSource : IRegistrationSource
{
public IEnumerable<IComponentRegistration> RegistrationsFor(
Service service,
Func<Service, IEnumerable<IComponentRegistration>> registrationAccessor)
{
var ts = service as TypedService;
if (ts != null && !ts.ServiceType.IsAbstract && ts.ServiceType.IsClass)
{
var rb = RegistrationBuilder.ForType(ts.ServiceType);
return new[] { RegistrationBuilder.CreateRegistration(rb) };
}
return Enumerable.Empty<IComponentRegistration>();
}
}
{
public IEnumerable<IComponentRegistration> RegistrationsFor(
Service service,
Func<Service, IEnumerable<IComponentRegistration>> registrationAccessor)
{
var ts = service as TypedService;
if (ts != null && !ts.ServiceType.IsAbstract && ts.ServiceType.IsClass)
{
var rb = RegistrationBuilder.ForType(ts.ServiceType);
return new[] { RegistrationBuilder.CreateRegistration(rb) };
}
return Enumerable.Empty<IComponentRegistration>();
}
}
Configuring the container to use the new source is easy.
var builder = new ContainerBuilder();
builder.RegisterSource(new ResolveAnythingSource());
var container = builder.Build();
// Works now
var foo = container.Resolve<Foo>();
builder.RegisterSource(new ResolveAnythingSource());
var container = builder.Build();
// Works now
var foo = container.Resolve<Foo>();
One Small Caveat
You should probably be aware of one small gotcha that both of these samples exhibit. If you actually do register an implementation of Foo, then resolve all instances of Foo, you’ll find that both your registered component, plus the automatically-generated one, will be there. This is a very unlikely situation, but it might pay to keep it in mind.
If you found your way here looking for Autofac’s Prism integration, good news is right around the corner! The source for AutofacContrib.Prism is in the trunk, and just needs a few updates before it will get a proper release.
Parsing strings to System.Linq.Expression
The example included with the last post is probably a bit underwhelming, so I thought I’d include another.
This variation on the “good old calculator example” takes a string input like 1 + 2 * (3 + 4) and produces an equivalent System.Linq.Expression that can be executed to get the numeric value.
You can also play around with the very minimal included error handling abilities.
Check out the code for the parser and the driver program.
Sprache C#
No, I haven’t reverted to my ancestors’ tongue.* Sprache is a small library for parsing text from C#.
// Parse a number of capital 'A's in a row, e.g. "AAAA"
var parseA = Parse.Char('A').AtLeastOnce();
var parseA = Parse.Char('A').AtLeastOnce();
If you’ve spent any time with Haskell, you’ll be familiar with Parsec, a beautiful framework for building parsers in a functional manner.
Sprache is based on the same design (yes, the ‘m’ word applies here) ported to C# with some help from a couple of excellent tutorials.
I built Sprache as a learning exercise, but posted it to Google Code because there seems to be no other implementation with controlled source, an issue tracker, and a well-defined license. It could use some input from someone who really knows their stuff, so hopefully the public site will help find that person.
Check out the Sprache homepage for some examples and links.
*’Sprache C#’ as far as my limited German takes me, means ‘C# Language’.
