Add ServiceStack to your project to get started

The way to get started with ServiceStack is to just add it to your project via NuGet. Typically this means adding it to an Empty ASP.NET Web Application if you're just creating ASP.NET web services, but could also mean a Console Application or a Windows Service if you're creating a self-hosting ServiceStack service instead.

These packages include the Free Usage Quotas listed below. The list of supported packages are also listed on nuget.org/profiles/ServiceStack. Dedicated support for these pacakges is not available for non-Windows server platforms.

Just ServiceStack

The minimal installation of ServiceStack, create an Empty ASP.NET project and:

PM> Install-Package ServiceStack

Dependencies

  • ServiceStack.Common
  • ServiceStack.Client

The docs on Creating your first web service using ServiceStack's VS.NET Templates are an easy way to Get Started with ServiceStack.

Once comfortable with creating a ServiceStack web service, we also recommend exploring ServiceStack by walking through the EmailContacts solution for a guidance on the recommended layout and configuration of a typlical medium-sized ServiceStack project.

ServiceStack with OrmLite, Redis and adapters

Would like to use Redis and/or OrmLite, create an Empty ASP.NET project and:

PM> Install-Package ServiceStack.Server

Dependencies

  • ServiceStack
  • ServiceStack.Redis
  • ServiceStack.OrmLite

Server project includes Auto Query, the OrmLite Auth Repository and Redis MQ

Add ServiceStack with advanced HTML Support

If you plan on using ServiceStack to create HTML websites as well then you should instead start with one of these 2 packages below:

ServiceStack with Razor Support

You want to use ServiceStack's built-in support for Razor, Create an Empty ASP.NET Project and:

PM> Install-Package ServiceStack.Razor

Dependencies

  • ServiceStack

We recommend reading the Razor Rockstars website to explore ServiceStack's Razor features.

ServiceStack together with ASP.NET MVC

You want to use ServiceStack together with an ASP.NET MVC Website, Create an Empty ASP.NET MVC Project and:

PM> Install-Package ServiceStack.Mvc

Dependencies

  • ServiceStack

After it's added to your MVC Project you'll need to follow the guidelines in MVC Integration and ensure ServiceStack is properly integrated.

Message Queue Servers

ServiceStack's message-based design enables it to host Services on a variety of different transports including a number of different MQ Servers via the Messaging API all MQ Servers implement making it trivial to swap between different MQ Brokers.

Rabbit MQ

Rabbit MQ is a popular industrial strength open source implementation of the AMQP messaging protocol for communicating with message queue middleware that runs on all major operating systems.

PM> Install-Package ServiceStack.RabbitMq

Dependencies

  • RabbitMQ.Client
  • ServiceStack.Server

Running RabbitMQ on Windows

See the installation and getting started guide for a walkthrough on setting up Rabbit MQ on windows and accessing it from C#.

ServiceStack Rabbit MQ

See ServiceStack's Rabbit MQ docs for an explanation on how Rabbit MQ works with ServiceStack and details on its message workflow.

Redis MQ

If Redis is already apart of your infrastructure, Redis MQ is an attractive choice to use as an MQ Broker without needing to add any additional infrastructure dependencies.

PM> Install-Package ServiceStack.Server

 

In Memory MQ

ServiceStack.Server also includes an In Memory MQ option useful for testing and for when other MQ Broker options are not available. Although not being able to accept network requests limits its usefulness.

Using Redis or OrmLite?

If you've started with ServiceStack.Server you already have OrmLite and Redis, if not you can add them individually:

Redis Client

Redis is a popular and indispensable tool in creating high-performance systems. It's often used as a cache, but as it supports comp-sci collections, Pub/Sub, Transactions and server-side LUA scripting, it's finding more use-cases every day.

PM> Install-Package ServiceStack.Redis

Dependencies

  • ServiceStack.Common

Running Redis on Windows

See the Download and installation instructions for the 2 most popular ways of running redis on windows.

OrmLite

OrmLite is a fast, simple, convention-based, config-free lightweight ORM that uses code-first POCO classes and Annotation attributes to infer and generate RDBMS table schemas. It's simply provides extension methods over ADO.NET's IDbConnection so is highly-flexible and can even be easily used seamlessly with other Micro ORM's like that uses extension methods like Dapper.

OrmLite has packages for all major RDBMS's, and you just need to install the package for the one you're using, which typically for .NET will be SQL Server:

PM> Install-Package ServiceStack.OrmLite.SqlServer

Dependencies

  • ServiceStack.Common

Otherwise if you're using an alternative database, install the one you need:

Just ServiceStack.Text?

JSON, JSV, CSV Serializers

ServiceStack.Text is a high-performance dependency-free library that contains all of ServiceStack's text processing, automapping utilities.
It includes 100's of enhancements to .NET's built-in String, Stream, Bytes, List, Dictionary, Reflection, Task and WebRequest types.

You will only need to install this when using on its own as ServiceStack.Text is already a dependency on all other ServiceStack NuGet packages.

PM> Install-Package ServiceStack.Text

Android, iOS, Windows Store, WPF and Silverlight clients should install the ServiceStack.Client package:

PM> Install-Package ServiceStack.Client

 

Authentication

Open Id and OAuth2

ServiceStack already comes in-built with a number of Authentication providers out of the box. Additional Open Id and OAuth2 providers that require a dependency on DotNetOpenAuth are available to install separately:

Open Id

The Open Id package includes support for Google, Yahoo and My Open Id as well as a generic provider that lets you authenticate with any Open Id provider:

PM> Install-Package ServiceStack.Authentication.OpenId

Dependencies

  • ServiceStack
  • DotNetOpenAuth.Ultimate

OAuth2

The OAuth2 package lets you authenticated with Google OAuth2 and LinkedIn OAuth2:

PM> Install-Package ServiceStack.Authentication.OAuth2

Dependencies

  • ServiceStack
  • DotNetOpenAuth.Ultimate

The Social Bootstrap Api is a good showcase showing how to enable all authentication providers within a single project.

User Auth Repositories

ServiceStack allows you to persist your User Auth information in a variety of different back-end persistence providers. Redis and InMemory are built-in to ServiceStack whilst ServiceStack.Server includes the OrmLite Auth Repository letting you store Users Authentication information in any of the RDBMS's that OrmLite supports: Sql Server, Sqlite, MySql and PostgreSQL.

In addition to these options you can also persist UserAuth info in RavenDB:

PM> Install-Package ServiceStack.Authentication.RavenDB

Dependencies

  • ServiceStack
  • RavenDB.Client

Mongo DB:

PM> Install-Package ServiceStack.Authentication.MongoDB

Dependencies

  • ServiceStack
  • mongocsharpdriver

or NHibernate:

PM> Install-Package ServiceStack.Authentication.NHibernate

Dependencies

  • ServiceStack
  • Iesi.Collections
  • NHibernate
  • FluentNHibernate
Caching and Logging Providers

Caching

In Memory Caching is available in ServiceStack and ServiceStack.Redis includes the Redis cache client, whilst an OrmLiteCacheClient is available in ServiceStack.Server for utilizing an existing RDBMS as a distributed cache.

Other External caching providers are also available:

Memcached:

PM> Install-Package ServiceStack.Caching.Memcached

Dependencies

  • ServiceStack.Common
  • EnyimMemcached

AWS Dynamo DB:

PM> Install-Package ServiceStack.Caching.AwsDynamoDb

Dependencies

  • ServiceStack.Common
  • AWSSDK

Azure:

PM> Install-Package ServiceStack.Caching.Azure

Dependencies

  • ServiceStack.Common
  • WindowsAzure.Caching

Logging

ServiceStack also provides an implementation and dependency-free logging API with adapters for all of .NET's popular logging providers. It allows your business logic to bind to an easily-mockable and testable dependency-free interface whilst providing the flexibility to switch logging providers at runtime.

Console, Debug and Empty logging providers are already in ServiceStack, whilst you can use NuGet to get the adapter for your preferred logging framework:

Additional Formats

Protocol Buffers

Protocol Buffers is a high-performance, compact binary wire format invented by Google who use it internally so they can communicate with their internal network services at very high speed.

You can add it to ServiceStack with:

PM> Install-Package ServiceStack.ProtoBuf

Message Pack

Message Pack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON but it's faster and smaller and unlike ProtoBuf supports attribute-less POCOs.

You can add it to ServiceStack with:

PM> Install-Package ServiceStack.MsgPack

External Plugins

See the Documentation on Plugins for the complete list of built-in plugins that are available in ServiceStack.

Swagger API

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

ServiceStack implements the Swagger API in a separate package available with:

PM> Install-Package ServiceStack.Api.Swagger

Build Tasks

Compiled Razor Views

ServiceStack supports compiled views as a separate build task that can

  • Improve performance by eliminating compile times of Razor views
  • provides static compilation benefits by highlighting compile errors during development
  • simplifies deployment by avoiding having to deploy *.cshtml files as they end up pre-compiled in the containing Assembly

PM> Install-Package ServiceStack.Razor.BuildTask

See the docs on Compiled Razor Views for more info.

Portable ServiceStack Desktop Apps

In addition to compiling Razor Views, ServiceStack also has transparent support for embedded resources, allowing your entire application, razor views and web assets to be compiled into .NET dlls that can be ILMerged into a Single cross-platform .exe.

In addition to compiling razor views, the ServiceStack.Gap NuGet package changes all web assets in your VS.NET project to embedded resources.

PM> Install-Package ServiceStack.Gap

See the docs on ServiceStack.Gap project for guides on how to create portable ServiceStack-powered Console, WinForms and Cocoa OSX Desktop Apps.

Website Bundling and Minification

Bundler

Bundler is a fast, cross-platform, command-line runner (easily integrated into existing IDEs, inc VS.NET) with optimized support for ASP.NET MVC and ServiceStack that statically compiles, minifies and combines your websites less, sass, stylus, css, coffeescript, livescript and js files.

You can add it to your ServiceStack or ASP.NET MVC project with:

PM> Install-Package Bundler

As ServiceStack is just a pure HTTP web service it can be accessed with any HTTP-capable client. However in order to provide the least friction and most productivity end-to-end, we also maintain generic C# clients available at:

PM> Install-Package ServiceStack.Client

Also includes Android, iOS, Windows Store, WPF and Silverlight clients, see Mobile documentation for more info.

Signed versions of the client libraries are also available at:

PM> Install-Package ServiceStack.Client.Signed

See the Hello Repository for a portable solution showing how to re-use DTO's and client libraries between Android, iOS, Windows Store, WPF and Silverlight platforms.

 

Service Clients are unrestricted

Explicitly included in the free quotas is an exception enabling free, unrestricted use of ServiceStack Service Clients for calling any ServiceStack service.

 

Signed Packages

Signed NuGet packages are available for core ServiceStack projects in separate NuGet packages using the .Signed suffix.

The following signed packages are available:

 

External Libraries

Stripe

Contains a typed .NET client gateway for accessing Stripe's REST API to process merhcant payments and recurring subcriptions online.

PM> Install-Package ServiceStack.Stripe

See the Stripe GitHub repository for documentation and example source code.

 

Registering your License Key with your ServiceStack Projects

The ServiceStack license key allows un-restricted access to ServiceStack packages and is available in your My Account Section after purchasing a commercial license.

There are multiple ways of registering your license key, all options only need to be added to your top-level host projects:

a) Add it to your Web.Config

The easiest way to register your license key is in to copy the servicestack:license appSetting into your Web.config or App.config's <appSettings/> config section, e.g:

<appSettings/>
    <add key="servicestack:license" value="{licenseKeyText}" />
</appSettings>

b) Add it in code before your Application Starts Up

By calling Licensing.RegisterLicense() before your application starts up, E.g. For ASP.NET, place it in the Global.asax Application_Start event:

protected void Application_Start(object sender, EventArgs e)
{
    Licensing.RegisterLicense(licenseKeyText);
    new AppHost().Init();
}

Otherwise for a self-hosting Console Application, place it before initializing the AppHost, as shown above.

c) Copy license key text into an external text file

Similar to above, we can register the license from an external plain-text file containing the license key text, e.g:

protected void Application_Start(object sender, EventArgs e)
{
    Licensing.RegisterLicenseFromFileIfExists("~/license.txt".MapHostAbsolutePath());
    new AppHost().Init();
}

For Self-Hosting set the BuildAction to Copy if Newer and use "~/license.txt".MapAbsolutePath() extension method.


Note: the license key is white-space insensitive so can be broken up over multiple lines.

Free Quotas

Whilst ServiceStack v4 is a commercially-supported product, we also allow free usage for small projects and evaluation purposes.
The NuGet packages above include the quota's below which can be unlocked with a license key:

* These quotas are lifted in ServiceStack.Client generic service clients allowing un-restricted access when consuming ServiceStack services.

Older releases of ServiceStack

Older, unsupported legacy v3.x builds of ServiceStack continue to remain on NuGet under the BSD license.

Documentation, Content and NuGet updates for v3

The ServiceStackV3 repository maintains a content archive of information for v3 including wiki documentation, Installation and updating instructions for NuGet as well as links to the v3 branches containing the BSD source code.