Tinyweb Series: 1 Getting Started

Tinyweb is an open source project I started last November with the goal of creating a minimal, service-oriented web application framework. I’ve been committing to the project ever since and it has now reached a level of maturity I’m happy with.

Full documentation for the project was completed recently and I figure it’s time to write a how to series of posts that cover the most interesting aspects of the framework.

So here we are with the first instalment. My goal for part 1 is to explain the thinking behind the project and show you how easy it is to file –> new project.

What’s Tinyweb?

From the docs:

Tinyweb is a lightweight web framework for ASP.NET that embraces HTTP and aims to be ridiculously simple.

Approaching the project with a background in using the MVC pattern, my goal was to move away from the issue of fat controllers and provide less abstraction over the core functionality of HTTP.

In Tinyweb, the URL, or more precisely the resource is the starting concept. By resource, I mean a single entity addressable by its URL and able to respond to any of the standard HTTP methods.

The resource is just a simple class with methods for each HTTP method it wishes to respond to, for example:

public class SignupHandler
{
    IUserService _userService;

    public SignupHandler(IUserService userService)
    {
        _userService = userService;
    }

    public IResult Get()
    {
        return View.Spark("Views/Signup.spark");
    }

    public IResult Post(UserModel user)
    {
        _userService.CreateUser(user);
        return Result.Redirect<WelcomeHandler>();
    }
}

Because the SignupHandler has a single URL and can only respond to the core HTTP methods, a certain level of SRP is enforced by this model. Tinyweb encourages an application to be broken into separate resources that collectively form a coherent system.

Tinyweb leans more toward a service-oriented approach to building web applications, where every endpoint within the system has a well defined purpose and collaboration between endpoints is used to form more complex behaviours. This is particularly fitting for pure JSON or XML APIs and I’ll be covering some related features of Tinyweb later in the series.

Another underlying goal of Tinyweb is simplicity. The framework itself is small, with a tiny pipeline and simple conventions to save you having lots of configuration. Conventions aren’t concrete and can be overridden, but using Tinyweb should to be fun, easy and consistent.

File –> New Project

So, let’s see how we create a new project using Tinyweb.

We’ll need an empty project to start with, so go ahead and create a new ASP.NET Empty Web Application project in Visual Studio. Done it?

OK, next we need to install the latest version of Tinyweb using the wonderful NuGet. Open the Package Manager Console and cast this spell:

Install-Package Tinyweb

NuGet will go and grab the relevant assemblies and add them to your exciting new empty project. Once done, Tinyweb is installed and ready for us to start writing some code.

Fortunately Tinyweb doesn’t require you to add anything to the web.config. Instead, Tinyweb is initialised from within Global.asax. You won’t have one yet, so you’ll need to add a new Global.asax file to your project. After you’ve added it, initialise Tinyweb like so:

protected void Application_Start(object sender, EventArgs e)
{
    Tinyweb.Init();
}

That wasn’t too painful, was it? Tinyweb is now loaded and routes have been configured to the various handlers that were discovered. There are other things you can do at this point, but we’ll cover them later in the series. For now, this is all you need.

The Handler

All the required setup and initialisation is done, and we’re now ready to build our actual application. Since this is Tinyweb land, we need to think about the first resource our system will need. Given this is the introduction post, and I’m creatively numb, let’s be traditional. The first handler will respond to HTTP GET requests at /hello/world and respond with the message Hello World. Exciting huh? Just me then?

public class HelloWorldHandler
{
    public IResult Get()
    {
        return Result.String("Hello World");
    }
}

Pretty simple, but let’s break it down and understand what’s going on here.

The Handler Name

Firstly, notice how the class doesn’t implement any base or interface. A handler is a handler if it ends in Handler. Say that fast 10 times. When Tinyweb.Init is called, handlers are discovered by scanning for classes that end with the word Handler. There’s the first convention.

The first part of the handler name is significant too. Breaking it up into its constituent Pascal-cased words, the handler name is used to build the URL of the resource. Because our handler is named HelloWorldHandler, Tinyweb produces the URL /hello/world.

Had the handler been called HomeHandler, we’d have the URL /home, or YabaDabaDooHandler would be addressable at /yaba/daba/doo. There’s the second convention.

The Handler Method

Next we have the method itself. Tinyweb recognises four potential methods which mirror the underlying HTTP methods, i.e. Get, Post, Put and Delete. You can also have Before and After methods, but we’ll talk about those later in the series.

Notice how the method returns IResult. This is the interface used to represent a handler response. Handlers must have a return type of IResult to be properly discovered. Tinyweb supports a number of result types including Result.String, Result.Json and View.Spark and we’ll look at these in the next post.

Finally, the handler returns a value to the client by using the static Result class. Result provides access to the supported result types while View provides access to the supported set of view engine results. Tinyweb currently ships with support for the Spark view engine.

In This Post

I introduced Tinyweb – the minimal web framework that encourages the use of concepts from HTTP to build service-style applications using ASP.NET. I talked about Tinyweb’s core goal of simplicity and explained how Tinyweb makes use of conventions and discovery to keep your code as simple as possible.

We built an example application, demonstrating how to install, initialise and write our first handler. We then dug a bit deeper into the method used for generating handler URLs and looked at what a handler can do.

Until Next Time

If you want to dive in and have a play around, simply install Tinyweb from NuGet, check out the documentation and if you have any questions, I’d be happy to help.

Next time we’ll look at the different types of content that can be returned by a handler, and look specifically at some features which are aimed at building JSON/XML APIs.