Edit on GitHub

v4 Release Notes

We’re happy to announce that after months of intense development, v4-beta of ServiceStack has finally been released to NuGet!

As announced in August to ensure it’s continued development, ServiceStack has moved to a self-sustaining commercial model for commercial usage of ServiceStack from v4+ onwards. It’s the first time we’ve been able to commit full-time resources to the project and is what has ensured continued investment and enabled v4 to be possible, with even more exciting features in the pipeline and roadmap for 2014.

Free Usage for Small and OSS Projects

We’re also happy to announce that v4 includes free quotas allowing the free usage of all of ServiceStack for small projects and evaluation purposes. Whilst OSS projects are able to use the source code on GitHub under the AGPL/FOSS License Exception, and the older v3 of ServiceStack continues to be available under the BSD license.

Upgrading from v3

Whilst we recommend starting with v4 for greenfield projects, v4 has seen significant changes since v3 that will require some development effort to upgrade. During the upgrade we recommend using a tool like ReSharper to be able to easily find and update reference of any types that have moved.

What’s new in v4

The major version upgrade of ServiceStack to v4 has provided us a long sought breaking window opportunity allowing us to re-factor, simplify, clean-up and fix all the warts and cruft that has been lingering in the ServiceStack code-base since its beginning - that due to backwards compatibility we were reluctant to remove. Whilst v4 has seen significant changes to the code-base, all existing tests are passing again with additional tests added for new functionality.

We managed to retain a lot of the user-facing API’s (E.g New API, AppHost, Config) which were already considered ideal so ideally upgrading shouldn’t be too disruptive in the normal use-cases.

v4 provides us a great foundation to build on that will be further improved during the beta by focusing on stability and fixing any reported issues as well as updating existing documentation to match v4’s implementation and publish new examples showcasing v4’s new features.

The big refactor of v4

This was the biggest re-factor in ServiceStack’s history which at the end resulted in a much leaner, simplified, consistent and internal logically-structured code-base that’s much easier to reason about, where even before adding any features the main ServiceStack repository saw:

1,192 changed files with 18,325 additions and 29,505 deletions. 

The number of deletions is indicative of how much legacy code was able to be removed, with much of the internals having been heavily restructured. Some of the highlights during the re-factor include:

RequestContext now merged into new IRequest / IResponse classes:

An annoyance remaining in the ServiceStack code-base was RequestContext and its relationship with its IHttpRequest and IHttpResponse classes. This was originally modeled after ASP.NET’s relationship with HttpContext and its child HttpRequest/HttpResponse classes. Pragmatically speaking this model isn’t ideal, as there was functionality spread across all 3 classes, many times duplicated. It was also not obvious how to retrieve IHttpRequest/IHttpResponse classes from a RequestContext and creating a RequestContext from outside of ServiceStack required more knowledge and effort than it should have.

The new model adopts a flattened structure similar to Dart’s server HttpRequest (http://bit.ly/19WUxLJ) which sees the IRequestContext eliminated in favour of a single IRequest class that also makes available direct access to the Response.

This now becomes much easier to create a Request from outside of ServiceStack with an ASP.NET or HttpListener HttpContext e.g:

var service = new MyService {
    Request = HttpContext.Current.ToRequest()

var service = new MyService {
    Request = httpListenerContext.ToRequest()

There’s also direct access to the Response from a Request with:

IResponse response = Request.Response;

ASP.NET wrappers now only depends on HttpContextBase

Also the ASP.NET IHttpRequest wrappers bind to the newer and mockable HttpContextBase / HttpRequestBase / HttpResponseBase classes which now makes it easier to call services from newer web frameworks like MVC with:

var service = new MyService {
    Request = base.HttpContext.ToRequest()

The biggest user-facing change was renaming the IHttpRequest/IHttpResponse classes to IRequest/IResponse which is more indicative to what they represent, i.e. the Request and Response classes for all endpoints including MQ and future TCP endpoints. Now only HTTP Requests implement IHttpRequest/IHttpResponse which lets you add logic targeting only HTTP Services with a simple type check:

var httpReq = request as IHttpRequest;
if (httpReq != null) {
    //Add logic for HTTP Requests...

Accessing the IHttpResponse works the same way, e.g:

var httpRes = Request.Response as IHttpResponse;
if (httpRes != null) {

We’re still going to add extension methods on IRequest/IResponse to make it easier to discover new functionality, but for HTTP functionality on non-HTTP requests these would just be a NO-OP rather than throw an exception.

Community v4 migration notes

New Features in v4

Server-side Async Support

The most requested feature, Server-side async support has now been implemented! This was surprisingly easy to do where now all HttpHandlers in ServiceStack inherit from a common HttpAsyncTaskHandler base class that now implements IHttpAsyncHandler. This lets you return an async Task from your Service in any number of ways as shown in http://bit.ly/1cOJ3hR

E.g. Services can now have either an object, Task or async Task return types that can return a started or non-started task (which we’ll start ourselves). This transition went as smooth as it could where all existing services continuing to work as before and all tests passing.

ServiceStack Client Task-based Async

In matching the new server-side async story and now that all projects have been upgraded to .NET 4.0, all Service Clients have been changed to return .NET 4.0 Task’s for all async operations so they can be used in C#’s async/await methods. Some examples of Async in action: http://bit.ly/17ps94C

The Async API’s also provide a OnDownloadProgress callback which you can tap into to provide a progress indicator in your UI, E.g: http://bit.ly/19ALXUW

Use any Request DTO in Client API’s

ServiceClient API’s that used to only accept Request DTO’s with a IReturn marker, now have object overloads so they can be used for unmarked Request DTO’s as well.

Custom Silverlight and Android builds

We’ve added custom Silverlight and Android automated builds for ServiceStack.Client allowing the client libraries to be available in even more environments - with more to follow.

Signed NuGet Packages

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

ServiceStack.Interfaces is now strong-named

In order to be able to have signed clients sharing types with non-signed ServiceStack instances, the DTO models and ServiceStack.Interfaces need to be signed. It was added in the most defensive way possible where ServiceStack.Interfaces.dll is the only dll that’s strong-named by default. This should cause minimal friction as it is an impl-free assembly that rarely sees any changes. We’re also keeping the AssemblyVersion which makes up the strong-name at a constant 4.0 whilst the benign AssemblyFileVersion will report the true version number.

Add Code-first Attributes at runtime, de-coupled from POCO’s

Inspection of all Metadata attributes in ServiceStack now uses ServiceStack.Text’s attribute reflection API’s which support adding of type and property metadata attributes dynamically. This now lets you add the same behavior normally only available via attributes, dynamically at StartUp. Some benefits of this include: being able to keep unattributed data model POCOs in OrmLite or to extend built-in and external Request DTOs and Services with enhanced functionality that was previously only available using attributes.

Fluent route configuration available in Reverse Routing

Leveraging the dynamic attribute support, we now include fluent Route definitions when retrieving relative or absolute urls in Reverse Routing, which can be used in Services when returning urls in responses and is also used in Service Clients to determine which routes to use. Note: as Fluent Routes are defined in the AppHost, they aren’t registered and therefore not available in disconnected .NET client applications - so using [Route] attributes on Request DTO’s remains the best way to share route definitions on both client and server.

Priority was added to [Route] attributes so auto-generated routes are given less precedence than explicit user-defined custom routes when selecting the best matching route to use.

The Virtual FileSystem

The Virtual FileSystem is now fully integrated into the rest of ServiceStack, this enables a few interesting things:

The VFS now elegantly lets you replace built-in ServiceStack templates with your own by simply copying the metadata or HtmlFormat Template files you want to customize and placing them in your folder at:

/Templates/HtmlFormat.html        // The auto HtmlFormat template
/Templates/IndexOperations.html   // The /metadata template
/Templates/OperationControl.html  // Individual operation template

This works because the ServiceStack.dll is the last assembly in Config.EmbeddedResourceSources.

API-first development

We’re starting to optimize ServiceStack’s HTML story around an API-first style of web development (particularly well suited to ServiceStack) in which services are developed so they naturally support both web and native clients from the start. Effectively this means that the HTML views are just another client that escapes C# earlier and leverages JS+Ajax to provide its dynamic functionality, and any HTML-specific functionality is encouraged to be kept in Razor views rather than using post backs to generate different server-side HTML representations.

Having developed the new servicestack.net website in this way, we’ve found it to be a lot more productive and responsive than standard server-side MVC development that we we’re accustomed to in .NET as JavaScript ends up being more mallable and flexible language with a smaller and reflective surface type area making it better suited in string manipulation, generating HTML views, consuming ajax services, event handling, DOM binding and manipulation, etc.

We’ve begun taking advantage of the Virtual FileSystem to ship embedded resources enhancing ServiceStack’s JS integration with client-side libraries like ss-utils.js that we maintain and update alongside the rest of ServiceStack’s dlls. Whilst we intend to create more examples in the near future showcasing this functionality, here’s an overview of what’s been added:

Improved Razor Support

Improved Server-side validation

The server-side validation story has also been improved with MVC’s HTML INPUT and Validation Helpers rewritten to look at ServiceStack error responses (earlier lost in the upgrade to Razor 2.0) and making use of the same bootstrap conventional classes that the client-side Ajax validation uses letting you maintain a single style of error feedback for both validation styles. It also now looks at state contained in the POST’ed data when rendering the HTML INPUT controls.

Fallback Routes

The default Razor views are now also processed by the FallbackRoute if one exists, enhancing the story for Single Page Apps who want requests to un-specified routes to be handled by client-side routing instead of returning 404’s.

Pre-Request filters

Direct (i.e. No Controller) Razor views and static file handlers now have pre-request filters applied to them, so they can be used for adding global behavior across all ServiceStack service and page requests.

Precompilation option for Razor Views

New options have been added to RazorFormat PrecompilePages and WaitForPrecompilationOnStartup that allow you to precompile razor views on startup and specify whether or not you want to wait for compilation to complete are now options available when registering the RazorFormat. As these can slow down dev iteration times they are not done when Config.DebugMode (aka development mode), but are otherwise enabled by default for production.

Other Razor Improvements

CORS Feature

CorsFeature now by default automatically handles all HTTP OPTIONS requests so you no longer have to explicitly allow for OPTION requests in your routes: http://bit.ly/19HbMVf

Can be disabled with:

Plugins.Add(new CorsFeature { AutoHandleOptionsRequests = false })


The Auth Tables are now called UserAuth and UserAuthDetails and implements the IUserAuth and IUserAuthDetails interfaces. For advanced customization, these tables can now be extended using custom models inheriting these interfaces by using the generic AuthRepository types, e.g:

Where the common non-generic OrmLiteAuthRepository is just a concrete impl inheriting from OrmLiteAuthRepository<UserAuth, UserAuthDetails>. Use InitSchema() to ensure missing Auth Tables are created at registration.

New optional UserAuthRole table added

A new UserAuthRole class was created for users who would prefer roles to be managed in separate tables rather than blobbed with the UserAuth table and session. E.g. You can change your custom session to check the database for asserting required users and permissions with:

public class CustomUserSession : AuthUserSession
    public override bool HasRole(string role)
        using (var db = HostContext.TryResolve<IDbConnectionFactory>().Open())
            return db.Count<UserAuthRole>(q => 
                q.UserAuthId == int.Parse(UserAuthId) && q.Role == role) > 0;

    public override bool HasPermission(string permission)
        using (var db = HostContext.TryResolve<IDbConnectionFactory>().Open())
            return db.Count<UserAuthRole>(q => 
                q.UserAuthId == int.Parse(UserAuthId) && q.Permission == permission) > 0;

Support for Max Login Attempts

The OrmLiteAuthRepository now supports automatically locking out user accounts after reaching the maximum number of Login attempts which can be specified at registration, e.g:

container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepository(c.Resolve<IDbConnectionFactory>()) {
        MaxLoginAttempts = appSettings.Get("MaxLoginAttempts", 5)

To opt-in to use the new locking behavior provide a value for MaxLoginAttempts as shown above. The above registration first uses the value overridable in appSettings if it exists, otherwise it defaults to a Maximum of 5 login attempts.

Adhoc locking of User Accounts

The CredentialsAuthProvider also supports locking user accounts by populating the UserAuth.LockedDate column with a non-null value. Set it back to null to unlock the account.

Initializing Auth Repository Schemas

Some Auth Repositories like OrmLite require an existing schema before they can be used, this can be done in the AppHost with:

//Create missing Auth Tables in any Auth Repositories that need them

This was previously named CreateMissingTables() and is safe to always run as it’s a NO-OP for Auth repositories that don’t require a schema and only creates missing tables, so is idempotent/non-destructive on subsequent runs.

New AuthWeb Test project

A new test project testing all Authentication providers within the same ServiceStack ASP.NET Web Application is in ServiceStack.AuthWeb.Tests.


AppSettings can now be passed a tier in the constructor, e.g. new AppSettings(tier: "Live") which it uses as a prefix to reference Tier-specific appSettings first, e.g:

<add key="Live.AppDb" value="..." />

Before falling back to the common key without the prefix, i.e:

<add key="AppDb" value="..." />

AppSettings now allows a Parsing Strategy, e.g. You can collapse new lines when reading a complex configuration object in Web.Config <appSettings/> with:

var appSettings = new AppSettings { 
    ParsingStrategy = AppSettingsStrategy.CollapseNewLines 

Nested Request DTOs

Using nested types as Request DTO’s are now supported. Nested Request DTO types include the names of their containing class to form their unique name, allowing the use of multiple nested types with the same name, which is potentially interesting to be used as a versioning strategy.

Localized symbols

I’ve added IAppHost.ResolveLocalizedString support in this commit which lets you override the built-in English symbols used in ServiceStack, e.g. this lets you change built-in ServiceStack routes, e.g: /auth, /assignroles, ?redirect=, etc. into something more appropriate for your language.

Other New Web Framework Features


Improved Consistency

As the API surface of OrmLite expands it became a lot more important to focus on better consistency which now sees all alternative aliases having been removed in favor of standardized naming around SQL equivalents (e.g Select,Insert,etc). Also the parameterized APIs and the C#-like string.Format API’s have now been merged with the parameterized APIs now being the default and the string.Format API having a ‘Fmt’ suffix.

Most of these APIs now have XML docs and Examples for a better Intelli-sense experience. We’ve also provided them in a list along side it’s generated SQL in these API tests

Some notes:

OrmLite extension methods are now mockable

OrmLite API’s can now be mocked by injecting a ResultsFilter letting you mock the results return by OrmLite which it will use instead of hitting the database. You can also mock with a filter function and it also supports nesting, see examples at: http://bit.ly/1aldecK

This will be useful in Unit Testing Services that access OrmLite directly instead of using a repository.

Support for references, POCO style

We’ve added a cool new feature to Store and Load related entities that works great on POCO which are enabled when you use the [Reference] attribute, e.g: http://bit.ly/1gmvtV6

Unlike normal complex properties in OrmLite:

Basically it provides a better story when dealing with referential data that doesn’t impact the POCO’s ability to be used as DTO’s. At the moment it’s limited to loading and saving on a Single instance. We’ll look at optimizations for batches on this in future.

We’re going to be giving OrmLite a lot more attention from now on given that we’re working full-time on ServiceStack and are using it exclusively for our .NET RDBMS persistence. We also intend on adding specialized support to take advantage of PostgreSQL’s new features like their HStore and native JSON support. PostgreSQL has been offering the best features of both RDBMS and NoSQL worlds lately and has recently become a particularly attractive option now that AWS is offering first-class support for PostgreSQL in both their RDS and Redshift services.


HTTP Utils are now mockable

Following in the steps of now being able to Mock OrmLite, the HTTP Utils extension methods (http://bit.ly/WyV2tn) are now mockable, e.g:

using (new HttpResultsFilter {
    StringResult = "mocked"
    //All return "mocked"
    "http://google.com".GetStringFromUrl(accept: "text/csv");
    "http://google.com".PostJsonToUrl(json: "{\"postdata\":1}");

More examples showing how all HTTP Apis can be mocked are at: http://bit.ly/HdWmgm

New pre-release MyGet Feeds

Instead of publishing pre-release packages on NuGet, we’re instead going to release our interim packages to MyGet first which provides greater control and allows better management of packages.

The Instructions to add ServiceStack’s MyGet feed to VS.NET are:

  1. Go to Tools -> Options -> Package Manager -> Package Sources
  2. Add the Source https://www.myget.org/F/servicestack with the name of your choice, e.g. ServiceStack MyGet feed