Self Host ASP.NET Web Api as a Windows Service

In my previous blog I demonstrated how to Self Host ASP.NET Web API, which was a very basic console application leveraging Owin and Katana.

The next step in this series is how to turn your console application into a Windows service.

Windows Service Template

The typical way to create a Windows Service is by using the Windows Service template when creating a new project within Visual Studio.

The template will create a Program.cs calling ServiceBase.Run() in the Main() method.

SelfHostServiceBase is the code that will extend ServiceBase.   You would have to implement OnStart() and OnStop()

That’s simplest possible implementation.  Now when you start debugging, you are treated with this wonderful message.

service

What this means is you must build your Windows service, start it, then attach the debugger to the process.

Doesn’t sound like a fun way to debug does it?

Topself

TopshelfThere is a great open source project called Topshelf which allows you to create a windows service which is much easier to debug.

Topshelf is a framework for hosting services written using the .NET framework. The creation of services is simplified, allowing developers to create a simple console application that can be installed as a service using Topshelf. The reason for this is simple: It is far easier to debug a console application than a service. And once the application is tested and ready for production, Topshelf makes it easy to install the application as a service.

First thing is to install Topshelf into your project via nuget.

Install-Package Topshelf

Next we need a tiny bit of code to configure our service with topshelf.

We tell topself which class will contain our service (TopselfService) as well as which method to call when the service starts and stops.

Also, you can define which user the service should run as, as well as the name, display name and description.

Now when you debug the application, it will run just like a Console application, in which you can add breakpoints and debug.

Self Host ASP.NET Web API

To verify my web api application is responding, here is the result from my Postman call

Postman

 

Source Code

GithubThe source code for this demo is available on Github.

Next…

Next up I’ll continue adding to the demo by serving static assets from your self host application.

Read More

How to Self Host ASP.NET Web Api

OWINOver the past several months, I’ve talked to a few people that were completely unaware that you could self host ASP.NET Web Api application without the need for IIS.

Anyone who has worked with IIS knows that sometimes it can feel a bit heavy.  Especially if you not using any other features other than serving static content or executing your ASP.NET Web Api.

There are a couple important aspects to cover first which are what makes self hosting possible.

OWIN

OWIN defines a standard interface between .NET web servers and web applications. The goal of the OWIN interface is to decouple server and application, encourage the development of simple modules for .NET web development, and, by being an open standard, stimulate the open source ecosystem of .NET web development tools.

To clarify and reword slightly, OWIN is a open source specification that is not defined by microsoft and is not an actual implementation.

Katana

Katana is an open source project by the Microsoft Open Technologies.  It’s a set of components for building and hosting OWIN-based web applications that follows the OWIN  specification.

I’m not entirely sure what the status is of OWIN/Katana within ASP.NET 5 (vNext), however I would like to think the separation between server, host, middleware, and application will continue.

Demo

All of the source code for this demo is available on Github.

The first thing we are going to do for this demo is create a Console Application and add the Owin SelfHost and WebAPI Owin Selfhost nuget packages

PM> Install-Package Microsoft.Owin.SelfHost

PM> Install-Package Microsoft.AspNet.WebApi.OwinSelfHost

Next, we will create a Startup class that will contain the HttpConfiguration similar to how you configure Web Api currently.   The startup class is the implementation of the OWIN specification that our OWIN Self Host implementation will use.  The Startup class must provide a public Configuration() method with the signature void.

Next, we will create a simple ApiController.

Last step is to add the web server implementation to out Program.cs Main() method.  This is done by simply calling out Katana implementation of WebApp.Start and passing our Startup class name as a type argument along with the host/port binding details as the first parameter argument.

That’s it!  Now when I make a call from Postman to http://localhost:8080/api/demo, here are the results:

selfhost

 

Source Code

GithubThe source code for this demo is available on Github.

Next…

Next up I’ll continue adding to the demo to illustrate how to easily turn the console application into a windows service, serving static content and other middleware.

Read More

Event Stream as a Message Queue

I was recently having a discussion around a system being built using Microsoft Azure.  Some concepts being discussed for this system where CQRS, Event Sourcing and Message Queue.

The diagram below is fairly typical when discussing CQRS and Event Sourcing.

Message Queue

One of the first things that stood out to me was the use of the Message Queue and Azure Service Bus.

For this blog post, I want to focus on the Service bus, which is used for publish-subscribe pattern.  The domain will emit events that are stored to the event stream and then will be published to the Service Bus.  Subscribers, such as Projections or other Bounded Contexts will process these events.

Forgotten Option

There is nothing wrong with using a service bus to publish domain events.

However, one option which is seemingly always forgotten to developers that are new to CQRS and Event Sourcing:

Your event stream can be used as a message queue

Other bounded contexts or projections can query/poll your event storage to retrieve new events that have been persisted.

At regular intervals, the event consumer could poll your event storage requesting any number of new events based on the last event it processed.

The consumer would be required to keep track of the last event it processed in order.  This provides some benefits as it may not be a process that is required to be continuously running.

You may be thinking: Polling? Really?

If you rolled your own event storage, I could understand how this might be problematic and would likely be easier to use a service bus.  Or you may want your event consumers to process the event as soon as possible.  Your implementation of how to handle this is dependant on how you are currently storing your events.

But the point still remains: Your event stream is a message queue.

As always, context is king.  Requirements and many other factors will play into how you want to handle messaging.

It is another option that may fit a scenario that you run into.

Event Store

Event Store

If you are just thinking about getting into Event Sourcing, I would highly recommend looking at Event Store by Greg Young as your event storage.

Event Store supports multiple types of Subscriptions including Competing Consumers.

Read More

ConfigR: Look Mom, No XML

driving-nohandsI stumbled upon ConfigR a several months ago  on twitter from Glenn Block.  It uses ScriptCS (and Roslyn) and was developed by Adam Ralph.

I finally got around to take it for a test drive on a side project.  It’s really a simple tool that I’ve been waiting for.

Why ConfigR?

The purpose of ConfigR is pretty straight forward.  It allows you to write C# code to define configuration settings which you would normally place in a the appSettings section of a web.config/app.config.

If you have used the appSettings at all, you probably wished they could be typed instead of always having to be strings.

From Adam Ralph, the creator of ConfigR

ConfigR allows you to write your config in C# instead of XML – that’s really all there is to it. From that point on you can use your imagination to go wild in what you do in that C#.

Install via NuGet

Make sure your project is set to be using .NET 4.5 or greater

You need to get ConfigR into your project.  Install via the Package Manager in Visual Studio.

PM> Install-Package ConfigR

Or if you prefer via the NuGet UI

configr2

Web Application

This portion has been updated to reflect the proper way of sing ConfigR with a web application.  Thanks to creator Adam Ralph for clarification below in the comments.

The default naming convention ConfigR uses to automatically load your configuration file is to look for a file in your output directly named Web.csx.

  1. Create a new file in your project named Web.csx
  2. Make sure the Copy to Output Directory is set to Do not copy.

This is different than a console app in which you do want to copy to output dir.  In a web application, we want the Web.csx in the same location as you would normally see the web.config.

ConfigR

I’m going to create two simple configuration settings in our new Web.csx file

As you can expect the Add method is adding items into the ConfigR global configuraiton.  The two configuration settings I’ve created are of different types: boolean and string.

Now in code when we need to access these configuration settings, it couldn’t be any easier.

Loading from Custom Location

Want to load a config file not using the default naming convention? Easy.

Complex Types

You can use complex types defined in your assembly or another referenced assembly.  When using a referenced assembly, you must specify the ScriptCS reference directive to the DLL in bin/ directory.

Here is my type defined in another referenced project called AnotherProject.dll

Here is my new Web.csx.  Again, note the #r ScriptCS reference directive and the using statement.

Now we can get our our complex type.

 

Read More

How to get started with CQRS & Event Sourcing

hammernailWhen I first heard about CQRS & Event Sourcing concepts through various blogs and videos, primarily from Greg Young and Udi Dahan, I wanted to apply it everywhere.

It seems really natural to want to take the limited knowledge we have about a new concept or technology and try and apply it to any problem.

Most of us know this is a terrible idea, but we are so tempted to push the concepts on a problem that it just doesn’t fit.

I realize I’m grouping CQRS and Event Sourcing together in this post.  Generally, if you are applying Event Sourcing then you are doing CQRS.  The other way around isn’t always true.

The Problem

In the very beginning I had a difficult time seeing where CQRS and Event Sourcing were best applied.  Again, as a beginner with our new shiny new knowledge we have our blinders on.

We look at any new problem and try to make it fit what we think CQRS and Event Sourcing solves.

There are some pretty good examples scattered around the internet about different situations that CQRS and Event Sourcing have been applied.  You may be able to read these examples and get a better understanding about what the context and how it was a good fit.  Also, you may read horror stories about how it was a complete failure and why.

To be honest, I haven’t read that many horror stories as I assume people are too afraid to admit their failures, although it would be very helpful to the community.

Feeling the Pain

I could read all kinds of blogs about where not to apply CQRS & Event Sourcing, but I need to feel the pain first hand to really understand where it’s best used.

I needed to apply the concepts I read about in a meaningful project.

For me a meaningful project was a side-project I worked on after hours at home that was large enough in scale that wasn’t incredibly trivial.

The learning experience of failure (and success) gave me greater insights and a deeper understanding to the words I’ve previously read from others discussing CQRS & Event Sourcing.

Practice

Start using CQRS and Event Sourcing in a project that is meaningful to you.  Obviously, I’m not recommending it in a project at work.  Do it in on a project where you can fail.  Feel the pain of applying these concepts where they don’t provide enough value or are cumbersome (hint: CRUD).

With real practice, your understanding matures and not everything will look like a nail with your shiny new hammer.

Read More

Handling Async Await Exceptions

Async Await Exceptions

Async/Await

There’s a ton of information about async await support in .NET 4.5.  I don’t want to go over all the best practices and gotchas in this post, but I did want to point out one common trend I’ve seen lately, which is handling async await exceptions.

Await or forget about it

Any async method that returns a Task or Task<T>, you should always await the result.

If you do not await, any exceptions that occur in the calling method will be swallowed.  Essentially you are turning the method call into a fire and forget.

Async Await Exceptions Example

Below is a simple example that demonstrates two behaviors of calling await on an async.  

To run the example, just copy and paste in a new console application.  If you run with the debugger, you should notice the following:

  1. MethodCallWithoutAwait will be called, however no exception will be raised in the debugger because await is not called.
  2. MethodCallWithAwait will be called and the exception will be raised in the debugger because await is called.

Async Lambdas

There be dragons!  Next post I’ll explore of using async lambdas and how you need to pay close attention in order to avoid creating a void lambda.

Read More

Mediator Pattern using MediatR and Unity

MediatRIn a couple previous posts I’ve discussed using Query Objects instead of Repositories and the Mediator pattern.  I find creating query objects being used with the command pattern much cleaner than polluting repositories with a ton of query methods.

The concept is nothing new as many people already use the command pattern in the context of executing commands/behavior following CQRS.   However, there is nothing wrong with using the same patterns for the query side.

I’ve been using my own home grown solution of the mediator pattern in a few different projects but had nothing really formalized.  I was thinking about creating a simple library until I stumbled upon MediatR created by Jimmy Bogard.

It is incredibly simple and only has one dependency, CommonServiceLocator.

The Github repo has a good set of docs and some examples with different dependency injection containers.

Unity RegisterType

I did notice the Unity example didn’t quiet work as described in the example.

The Mediator class takes a ServiceLocatorProvider in its constructor which was not being resolved properly by Unity.

In order to get it functioning correctly, I defined an injection factory and created the Mediator and passed in the UnityServiceLocator.

My complete Unity configuration which is also using MediatR to publish events from NEventStore:

MediatR v2.0

Although v1 has a dependency on CommonServiceLocator, it appears that v2.0 will not have any external dependencies.

MediatR

 

 

Read More

Domain Driven Design: “What” not “How”

Common LanguageMany years have past since Eric Evans release the blue book: Domain Driven Design.  A lot has changed over the years but I find the core ideas still hold very true.

In some ways, I think some of the concepts outlined are even more prevalent now than they have ever been.

Ubiquitous Language

The Ubiquitous Language is a shared language developed by the team.  The team is everyone working on the project: developers, domain experts, QA, BA.

Everyone on the team.

The ubiquitous language isn’t developed by the domain expert(s) alone.  If you have more than one domain expert, they may struggle with language between each other to define concepts.

Everyone apart of the team is building, growing and refining the language.

Language is critical to not only verbal communication but how it’s represented in the software we are writing.  It represents the concepts and terms specific to the core business domain we are trying to model.

All the expressions, nouns and verbs are what the team is formally defining with an ubiquitous language.

Bounded Context

Boundaries

One of my favorite concepts is of the bounded context.  Bounded context should be autonomous.

Meaning, a bounded context should be independent and self governing.

It defines a set of business capabilities within the domain and represents a conceptual boundary.

One way of determining where the boundaries lie is with the ubiquitous language.

If a term or phrase has a different meaning in another context, you may have discovered a boundary and therefor another bounded context.

“What”, not “How”

With the rise/hype of microservices, the concept of a bounded context continues to hold true.

How do functional languages impact domain driven design?  As I’m leaning F#, I’m not overly concerned about the “how”.

The important part modeling a domain for me is the verbs, not the state.  I do think that will translate well to a functional language.

Focusing on the what not the how is what makes Domain Driven Design still very important and applicable so many years later.

 

Read More

Clean up your Domain Model with Event Sourcing

Vacuum cleaner - Workers collectionI recently had a discussion with a developer who was new to Domain Driven Design, CQRS and Event Sourcing.  They were using Greg Young’s Simple CQRS Example to create there own simple app as learning exercise.

After taking a quick look at their aggregate root, one thing that immediately stood out to me was a class field that contained current state.  Why this is interesting is because this field was not in any invariant.

When I first started reading and exploring Event Sourcing, this was a big “ah ha!” moment for me.

The realization that only certain data within my domain model was really important.

We will use a simple shopping cart example.

First, lets look at what our shopping cart would look like without being event sourced. We would be probably persisting this to a relational database using an ORM or perhaps storing it in a NoSQL document store.

public class ShoppingCart
{
    public Guid Id { get; set; }
    public IList<ShoppingCartLineItem> LineItems { get; set; }
    public bool IsComplete { get; set; }
    public DateTime CompleteDate { get; set; }

    public ShoppingCart(Guid id)
    {
        Id = id;
        LineItems = new List<ShoppingCartLineItem>();
    }

    public void AddProduct(string productSku, int quantity)
    {
        if (string.IsNullOrEmpty(productSku)) throw new ArgumentException("productSku");
        if (quantity <= 0) throw new ArgumentException("quantity");

        LineItems.Add(new ShoppingCartLineItem(productSku, quantity));
    }

    public void Complete()
    {
        if (IsComplete) throw new InvalidOperationException("Already completed.");
        if (LineItems.Any() == false) throw new InvalidOperationException("Cannot complete with no products.");

        IsComplete = true;
        CompleteDate = DateTime.UtcNow;
    }
}

There are a few things to point out in the above code.

Take note of the public properties which represent our current state.  These are the pieces of data that we be persisted to data storage.

Notice we have a IList<ShoppingCartLineItem> which is our collection of products that are in our shopping cart.  The ShoppingCartLineItem class contains the Product SKU and the quantity ordered.

One invariant in this example to mention is in the Complete() method.  There must be at least one product added to the shopping cart in order to mark it as complete.

if (LineItems.Any() == false) throw new InvalidOperationException("Cannot complete with no products.");

Next, let’s implement the above with event sourcing.

public class ShoppingCart : AggregateRoot
{
    private Guid _id;
    private bool _completed;
    private DateTime _completedDate;
    private readonly IList _lineItems;
 
    public override Guid Id
    {
        get { return _id; }
    }

    private void Apply(ShoppingCartCreated e)
    {
        _id = e.Id;
    }

    private void Apply(ProductAdded e)
    {
        _lineItems.Add(new ShoppingCartLineItem(e.ProductSku, e.Quantity));
    }

    private void Apply(Completed e)
    {
        _completed = true;
        _completedDate = e.DateCompleted;
    }

    public ShoppingCart(Guid id)
    {
        _lineItems = new List();

        ApplyChange(new ShoppingCartCreated(id));
    }

    public void AddProduct(string productSku, int quantity)
    {
        if (string.IsNullOrEmpty(productSku)) throw new ArgumentException("productSku");
        if (quantity <= 0) throw new ArgumentException("quantity");

        ApplyChange(new ProductAdded(_id, productSku, quantity));
    }

    public void Complete()
    {
        if (_completed) throw new InvalidOperationException("Already completed.");
        if (_lineItems.Any() == false) throw new InvalidOperationException("Cannot complete with no products.");

        ApplyChange(new Completed(_id, DateTime.UtcNow));
    }
}

In our event sourced implementation above we still are holding current state in the same fashion as our non event sourced version.  I’ve changed them from public properties to private fields since they are not being persisted to data storage.  Instead our events raised through ApplyChange() are what are persisted to data storage.

The example above is typical of a first implementation of event sourcing.  We are taking the concept we know and use of persisting current state along with this new idea of using events as state transitions.

There is actually a lot of code that can be removed from our event sourced example above.

ShoppingCartLineItem class is no longer needed because the data it encapsulates is now encapsulated in our ProductAdded event.  So if we delete that class, then we have the issue with:

private readonly IList<ShoppingCartLineItem> _lineItems;

This private member will no longer be valid since we just deleted the ShoppingCartLineItem class.  So we can remove this private member as well.

Now let’s go back to that invariant that we have:

if (_lineItems.Any() == false) throw new InvalidOperationException("Cannot complete with no products.");

How can we maintain this invariant since we are no longer keep track of the line items?

You only need the data applicable to an invariant

Because of this, we don’t really care what products or quantities are on the shopping cart, just that there is at least one.

Any data that is not used by an invariant does not need to be in your aggregate.

private DateTime _completedDate;

We also no longer need the date the shopping cart was completed because it is not used by an invariant and it is also contained in the Completed event.

Now let’s take a look at our shopping cart with these ideas applied:

public class ShoppingCart : AggregateRoot
{
    private Guid _id;
    private bool _containsProducts;
    private bool _completed;

    public override Guid Id
    {
        get { return _id; }
    }

    private void Apply(ShoppingCartCreated e)
    {
        _id = e.Id;
    }

    private void Apply(ProductAdded e)
    {
        _containsProducts = true;
    }

    private void Apply(Completed e)
    {
        _completed = true;
    }

    public ShoppingCart(Guid id)
    {
        ApplyChange(new ShoppingCartCreated(id));
    }

    public void AddProduct(string productSku, int quantity)
    {
        if (string.IsNullOrEmpty(productSku)) throw new ArgumentException("productSku");
        if (quantity <= 0) throw new ArgumentException("quantity");

        ApplyChange(new ProductAdded(_id, productSku, quantity));
    }

    public void Complete()
    {
        if (_completed) throw new InvalidOperationException("Already completed.");
        if (_containsProducts == false) throw new InvalidOperationException("Cannot complete with no products.");

        ApplyChange(new Completed(_id, DateTime.UtcNow));
    }
}

The invariant is now based on a boolean set when a product has been added.  The aggregate does not care about what products were added or their quantity.  It doesn’t even need to have them in a collection.

With the implementation of event sourcing in our aggregate, we get a much clearer view of what data drives business logic and is important in our domain model.

Read More

Bounded Context and Subdomains

CarpetIn a previous blog, I discussed how I recently discovered through eventual consistency that I had poor business alignment.  With more thoughts and insights, I wanted to extend that post by discussion bounded contexts and how they fit within subdomains.

1 to 1?

I’ve often thought of a bounded context as being a one-to-one relationship with a subdomain.   To take that further, you may get the impression that they are indeed the same thing.  When I was first introduced to the concept many years ago, I was under the impression that they mapped directly one to one.

I’m not entirely sure why I had this perception early on.  It may be due examples or just the assumption I made.  I do not remember actually ever reading how a subdomain and a bounded context don’t map directly one to one.

Over the years I’ve realized this not to be the case, but always had a tough time giving an explanation that others could visualize.

I heard Eric Evans gave a great example that I will paraphrase, which should help you visualize the difference.

Living Room Floor

Imagine a room in your house.  It may have a closet or some different length walls which makes it not totally uniform.  Imagine there is carpet in this room.  The carpet covers every inch of the floor.  Wall to wall carpet.

This carpet represents your bounded context.

Underneath the carpet, say the cement, is your subdomain.

By Design

It just so happens that your bounded context is mapped to your subdomain exactly.  However, that is just because the bounded context (carpet) was designed that way.

A bounded context doesn’t necessarily need to cover the entire subdomain.  It only needs to cover the aspects of the subdomain which help solve the problem space.

To use the carpet analogy again, I mentioned that the room wasn’t completely uniform as maybe it had a closet in it.  The carpet doesn’t need to cover the entire floor beneath it.  There may be bare floor exposed in the closet because that portion of the subdomain doesn’t require to be modeled as it isn’t needed for problem you are trying to solve.

More Than One?

I’m still trying to determine if a subdomain can have more than one bounded context.  I do think it may be possible if you are implementing something technical apart of that subdomain.  I would love to hear others thoughts on this.

Read More