| Windows | Linux | NuGet | Azure Demo Website |
|---|---|---|---|
 |
 |
 |
Nano is a .NET cross-platform micro web framework for building web-based HTTP services and websites.
- Rapidly create web APIs by writing static methods
- Run self-hosted or within an ASP.NET website
- Add it as a C# single file drop in or referenced as a NuGet Package
- The Api Explorer is distributed as a single file drop in
- Easy setup and low ceremony so that you can focus on business logic and not infrastructure and framework hassles
- Api Explorer webpage saves you massive time!
- Enables exploring and invoking available endpoints and operations
- Displays XML source code documentation
- Enables rapid testing and doesn't require QA analysts to use external tools to invoke your web service
- Can serve as a "free" auto-generated UI that can be given to internal users
- Includes a built-in C# and JavaScript proxy generator which enables clients to generate a proxy to call your API
- Easy to use extension points for intercepting requests, responses, or errors in order to implement logging, authentication, authorization, etc.
- Allows developers to simply write static methods and have them automatically be exposed as JSON endpoints at a convention based URL. As fast as you can write a method is as fast as you can have an API.
- Ability to go low level by using the NanoContext class in the instance that you need to control content type, return blobs, handles headers or cookies, etc.
The Nano demo website and Api Explorer is hosted on Azure and can be viewed here.
There are also four different demo projects included demonstrating how to use Nano as a self-hosed console application, a self-hosted Windows service, a self-hosted Topshelf managed Windows service, or within an ASP.NET application.
Follow this five minute introduction to create your first self-hosted Nano application.
Step One - Create a new solution and a C# console application project called "NanoIsAwesome"
Step Two - Install Newtonsoft.Json from Nuget (This is the only dependency Nano has)
Step Three - Download the single-file drop-ins for both Nano (nano.cs) and the Api Explorer (index.html) and add them to your project structure which we recommend look like this:
├── NanoIsAwesome
├── Properties
├── References
├── Api
├── HelloWorldApi.cs
├── www
├── ApiExplorer
├── index.html
├── App.config
├── Nano.cs
├── packages.config
├── Program.cs
Step Four - Add the following Post-build event command line command which will copy the 'www' folder to the projects bin directory every time the project is built. In Visual Studio this can be found by right-clicking on the NanoIsAwesome project | Properties | Build Events | And pasting the command below into the "Post-build event command line" text box.
For Windows:
xcopy "$(ProjectDir)www\*.*" "$(TargetDir)www" /Y /I /E
For Linux:
mkdir -p $(TargetDir)www;
cp -rf $(ProjectDir)www\* $(TargetDir)www
Or you can optionally add the following directly to the projects .csproj file which will work for both Windows or Linux based environments:
<PropertyGroup>
<PostBuildEvent Condition=" '$(OS)' == 'Windows_NT' ">
xcopy "$(ProjectDir)www\*.*" "$(TargetDir)www" /Y /I /E
</PostBuildEvent>
<PostBuildEvent Condition=" '$(OS)' != 'Windows_NT' ">
mkdir -p $(TargetDir)www;
cp -rf $(ProjectDir)www\* $(TargetDir)www
</PostBuildEvent>
</PropertyGroup>
Step Five - Create a new class in the Api folder of your project named "HelloWorldApi". Then just copypasta the code below:
namespace NanoIsAwesome.Api
{
class HelloWorldApi
{
public static string HelloWorld()
{
return "Hello World!";
}
}
}Step Six - Update your Program.cs Main method to configure and start Nano. Just copy the code below. Feel free to read the comments if you’re curious about what each piece does:
static void Main(string[] args)
{
// Create a new configuration instance for Nano
var config = new Nano.Web.Core.NanoConfiguration();
// This exposes all public static methods in the HelloWorldApi class as JSON endpoints
config.AddMethods<HelloWorldApi>();
// Map the www directory so it can be served. This allows us to access the Api Explorer
// by browsing to the ApiExplorer sub-directory
if (Debugger.IsAttached)
{
// If we're debugging, we need to map the directory as it appears in the project
config.AddDirectory("/", "../../www", returnHttp404WhenFileWasNotFound: true);
}
else
{
// If we're not debugging, we can map the directory as it will appear in the deployed code
config.AddDirectory("/", "www", returnHttp404WhenFileWasNotFound: true);
}
// Start the Nano server using the config and tell it to run at the given URL
using (var server = Nano.Web.Core.Host.HttpListener.HttpListenerNanoServer.Start(config, "http://localhost:4545"))
{
System.Console.WriteLine("Press any key to exit.");
System.Console.ReadKey();
}
}Step Seven - Start the debugger and navigate to http://localhost:4545/ApiExplorer/ to use the built-in testing endpoint or http://localhost:4545/Api/HelloWorldApi/HelloWorld to hit the endpoint directly.
And that's it. You're successfully using Nano to serve a website and a JSON API endpoint. Visit the Getting Started Guide, the Nano Wiki, or browse the source code, unit tests, and demo projects to learn more.
The Api Explorer page is an integral part of the Nano experience as it allows you to interact with any of your web service endpoints with ease. Here is a quick list of features:
- Built-in C# and JavaScript proxy generator
- Displays method (operation) names, URLs, data types, and method and parameter XML comments
- Ability to search by API classes or methods
- Ability to invoke methods
- Displays API results along with HTTP status code and execution time
- Displays sample JSON input for methods that take complex objects
The Nano demo website and Api Explorer is hosted on Azure and can be viewed here.
Thank you to all of the contributors who have helped shaped Nano in big and small ways:
- Randy Burden - https://github.com/randyburden
- David Whitlark - https://github.com/dwhitlark
- Austen Jeane - https://github.com/aus10
- Jordan Beacham - https://github.com/jbeacham
- Dominique Harris - https://github.com/revnique
- Brian Schwarzkopf - https://github.com/bsschwa
- Robert Rudduck - https://github.com/rrudduck
- Michael Rudduck - https://github.com/mrudduck
- Rahul Rumalla - https://github.com/xizmark
- Andrew McClellen - https://github.com/acmc
- Taylor Wolfe - https://github.com/wolfester
- Jack Farrington - https://github.com/jackfarrington
- Brennon Meiners - https://github.com/BrennonEH
- Chris Cha - https://github.com/christophercha
- Rolando Rojas - https://github.com/rorojas
- Vishal Tahiliani - https://github.com/vishtahil
Thanks to the following companies for providing free resources to help us run this project:
- AppVeyor - Continuous integration build server for running our Windows tests
- Travis CI - Continuous integration build server for running our Linux (Mono) tests
- Microsoft Azure - Web hosting
Nano is open source licensed under the terms of the MIT License and available for free. See this projects LICENSE file for more information.
Nano made use of substantial portions and/or was heavily influenced by the following open source software:
-
Nancy: https://github.com/NancyFx/Nancy
The MIT License Copyright (c) 2010 Andreas Håkansson, Steven Robbins and contributors License available at: https://github.com/NancyFx/Nancy/blob/master/license.txt -
Katana Project: http://katanaproject.codeplex.com/
Apache License Copyright (c) Microsoft Open Technologies, Inc. All rights reserved. License available at: http://katanaproject.codeplex.com/SourceControl/latest#LICENSE.txt -
DynamicDictionary: https://github.com/randyburden/DynamicDictionary
The MIT License Copyright (c) 2014 Randy Burden ( http://randyburden.com ) All rights reserved. License available at: https://github.com/randyburden/DynamicDictionary/blob/master/LICENSE -
JSON.NET: https://github.com/JamesNK/Newtonsoft.Json
The MIT License Copyright (c) 2007 James Newton-King License available at: https://github.com/JamesNK/Newtonsoft.Json/blob/master/LICENSE.md