Many people will start a new ASP.Net Core project and choose Web API as their framework without giving it a second thought. It comes bundled with .Net Core, it has an abundance of users, and there’s a lot of existing documentation and reference material. But it’s not your only choice, and as we’ll see, the community supported NancyFx framework is a super-simple, yet powerful, alternative web app framework. Nancy is based on the Sinatra framework for Ruby and takes a “convention over configuration” approach, and as we’ll see this can make working with it a little different than some .Net developers are used to.
Setup
Nancy has a simple, low ceremony “happy path” that involves very little setup. There are just a couple steps to get up and running.
1. Because Nancy is an external package we will have to add a reference in our csproj file.
2. We need to let ASP.Net Core know we’re using Nancy in the Startup class. This is done by connecting Nancy through the OWIN interface. OWIN stands for Open Web Interface for .Net and it is designed to create a straightforward interface between the web server and the web app. You can read more about it here.
3. And lastly, we create a module by inheriting from the NancyModule class. Classes that inherit from NancyModule will be discovered on Startup, so you can put them anywhere you want. Routes and actions are defined within the constructors of modules, and in this case, we’ve setup an action to return “Hello World” from the root route in response to a GET request and a second action to return a different message in response to the “/about” route.
Input Binding
Put and Post requests often come with input parameters and Nancy provides an interesting way of handling this. Rather than attempting to map json to a static type it uses a Nancy defined type called DynamicDictionary. This dynamic type will always contain named values as they were structured in the JSON request body. This alleviates the need for explicit mapping at the expense of rigid type checking.
In this example, the user input will be DynamicDictionary and will contain properties corresponding to whatever was in the json request body. We can see at the end of the method that we are returning 200 if the user saved successfully, and 500 otherwise. Nancy automatically takes integer return values and maps them a response with the corresponding status number. This is a useful shorthand provided by Nancy.
View Engines and Templates
Nancy comes packaged with its own “Super Simple View Engine” that can be used with no additional setup. Here is a sample template that demonstrates features such as master pages, sections, and partials.
Returning a view from an action is as simple as placing an sshtml file in a location that Nancy is expecting and returning a value from the View indexer inside the action. “A location that Nancy is expecting” is vague, but Nancy is pretty flexible in terms of where you can place your views. The full topic gets fairly in-depth.
In this action we are returning a template with the filename about.sshtml, and passing it a model to bind to the template. If no model is needed this parameter can be left out.
The Super Simple View Engine is handy for very simple scenarios, but it’s lacking many advanced features contained by more robust view engines, such as Razor. Luckily, Nancy provides packages that allow integration with a range of popular view engines. For example, to work with the Razor, start by adding the appropriate Nuget package to the csproj file.
…Then create a class inheriting from IRazorConfiguration to set the Nancy Razor configuration parameters.
…And that’s it! Now you can reference your cshtml razor templates in Nancy just like you would an sshtml template.
Additional Reading
We’ve only scratched the surface of what’s possible with Nancy. The setup is deceptively simple, but under the hood it’s a remarkably powerful and configurable framework. If you’re interested in learning more check out these resources.
Exploring a minimal WebAPI with .NET Core and NancyFX
Getting Started With NancyFX In ASP.net Core
NancyFX Github Wiki (Useful, but be aware that at the time of writing much of this documentation had not been updated to include NancyFX 2.0 functionality)