ServiceStack v4.0.24

Server Events​

In keeping with our quest to provide a simple, lean and deep integrated technology stack for all your web framework needs we've added support in this release for Server push communications with our initial support for Server Sent Events.

Server Sent Events (SSE) is an elegant web technology for efficiently receiving push notifications from any HTTP Server. It can be thought of as a mix between long polling and one-way WebSockets and contains many benefits over each:

• Simple - Server Sent Events is just a single long-lived HTTP Request that any HTTP Server and Web Framework can support
• Efficient - Each client uses a single TCP connection and each message avoids the overhead of HTTP Connections and Headers that's often faster than Web Sockets.
• Resilient - Browsers automatically detect when a connection is broken and automatically reconnects
• Interoperable - As it's just plain-old HTTP, it's introspectable with your favorite HTTP Tools and even works through HTTP proxies (with buffering and checked-encoding off).
• Well Supported - As a Web Standard it's supported in all major browsers except for IE which can be enabled with polyfills.

Server Events provides a number of API's that allow sending messages to:

• All Users
• All Users subscribed to a channel
• A Single Users Subscription

It also includes deep integration with ServiceStack's Sessions and Authentication Providers which also sending messages to uses using either:

• UserAuthId
• UserName
• Permanent Session Id (ss-pid)

Registering​

List most other modular functionality in ServiceStack, Server Sent Events is encapsulated in a single Plugin that can be registered in your AppHost with:

Plugins.Add(new ServerEventsFeature());

ServiceStack Chat (beta)​

To demonstrate how to make use Server Events we've created a cursory Chat web app for showcasing server push notifications packed with a number of features including:

• Anonymous or Authenticated access with Twitter, Facebook or GitHub OAuth
• Joining any arbitrary user-defined channel
• Private messaging
• Command history
• Autocomplete of user names
• Highlighting of mentions
• Grouping messages by user
• Active list of users, kept live with:
  • Periodic Heartbeats
  • Automatic unregistration on page unload
• Remote Control
  • Send a global announcement to all users
  • Toggle on/off channel controls
  • Change the CSS style of any element
  • Change the HTML document's title
  • Redirect users to any url
  • Play a youtube video
  • Display an image url
  • Raise DOM events

Chat is another ServiceStack Single Page App Special showing how you can get a lot done with minimal effort and dependencies which delivers all these features in a tiny footprint built with vanilla jQuery and weighing just:

• 1 default.cshtml page with under 170 lines of JavaScript and 70 lines of HTML
• 2 ServiceStack Services entire backend in 1 .cs file
• 1 ASP.NET Web Application project requiring only a sane 9 .NET dll references

Remote control​

Chat features the ability to remotely control other users chat window with the client bindings in /js/ss-utils.js, providing a number of different ways to interact and modify a live webapp by either:

• Invoking Global Event Handlers
• Modifying CSS via jQuery
• Sending messages to Receivers
• Raising jQuery Events

All options above are designed to integrate with an apps existing functionality by providing the ability to invoke predefined handlers and exported object instances as well as modify jQuery CSS and raising DOM events.

The complete documentation in Chat is the recommended way to learn more about Server Events which goes through and explains how to use its Server and Client features.

ServiceStackVS - ServiceStack's VS.NET Extension​

Another exciting announcement is the initial release of ServiceStackVS - our VS.NET ServiceStack Extension containing the most popular starting templates for ServiceStack powered solutions:

Each project template supports our recommended multi-project structure promoting a clean architecture and Web Services best-practices, previously documented in Email Contacts.

This is now the fastest way to get up and running with ServiceStack. With these new templates you can now create a new ServiceStack Razor, AngularJS and Bootstrap enabled WebApp, pre-wired end-to-end in seconds:

Get the Learning AngularJS for .NET Developers Book!​

On ServiceStack and AngularJS front, we also have great content coming from the ServiceStack community as Learning AngularJS for .NET Developers, a new book by Alex Pop has just been made available.

More details about the book as well as downloadable code-samples is available on Alex's announcement blog post.

Download ServiceStackVS​

ServiceStackVS supports both VS.NET 2013 and 2012 and can be downloaded from the Visual Studio Gallery

VS.NET 2012 Prerequisites​

• VS.NET 2012 Users must install the Microsoft Visual Studio Shell Redistributable
• It's also highly recommended to Update to the latest NuGet.

Alternatively if continuing to use an older version of the NuGet Package Manager you will need to click on Enable NuGet Package Restore after creating a new project to ensure its NuGet dependencies are installed.

Feedback​

We hope ServiceStackVS helps make ServiceStack developers more productive than ever and we'll look at continue improving it with new features in future. Suggestions and feedback are welcome.

Authentication​

Saving User Profile Images​

To make it easier to build Social Apps like Chat with ServiceStack we've started saving profile image urls (aka avatars) for the following popular OAuth providers:

• Twitter
• Facebook
• GitHub
• Google OAuth2
• LinkedIn OAuth2

The users profile url can be accessed in your services using the IAuthSession.GetProfileUrl() extension method which goes through the new IAuthMetadataProvider which by default looks in UserAuthDetails.Items["profileUrl"].

New IAuthMetadataProvider​

A new IAuthMetadataProvider has been added that provides a way to customize the authInfo in all AuthProviders. It also allows overriding of how extended Auth metadata like profileUrl is returned.

public interface IAuthMetadataProvider
{
    void AddMetadata(IAuthTokens tokens, Dictionary<string, string> authInfo);

    string GetProfileUrl(IAuthSession authSession, string defaultUrl = null);
}

To override with a custom implementation, register IAuthMetadataProvider in the IOC

Saving OAuth Metadata​

The new SaveExtendedUserInfo property (enabled by default) on all OAuth providers let you control whether to save the extended OAuth metadata available (into UserAuthDetails.Items) when logging in via OAuth.

OrmLite​

Loading of References in Multi-Select Queries​

Previous support of pre-loading of references were limited to a single entity using LoadSingleById to automatically fetch all child references, e.g:

public class Customer
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }

    [Reference] // Save in CustomerAddress table
    public CustomerAddress PrimaryAddress { get; set; }

    [Reference] // Save in Order table
    public List<Order> Orders { get; set; }
}

var customer = db.LoadSingleById<Customer>(request.Id);
customer.PrimaryAddress   // Loads 1:1 CustomerAddress record 
customer.Orders           // Loads 1:M Order records 

We've now also added support for pre-loading of references for multiple resultsets as well with LoadSelect which loads references for all results, e.g:

var customers = db.LoadSelect<Customer>(q => q.Name.StartsWith("A"));

This is implemented efficiently behind the scenes where only 1 additional SQL Query is performed for each defined reference.

As a design goal none of OrmLite Query API's perform N+1 queries.

Self References​

We've extended OrmLite References support to support Self References for 1:1 relations where the foreign key property can be on the parent table, e.g:

public class Customer
{
    ...
    public int CustomerAddressId { get; set; }

    [Reference]
    public CustomerAddress PrimaryAddress { get; set; }
}

Which maintains the same relationship as having the Foreign Key column on the child table instead, i,e:

public class CustomerAddress
{
    public int CustomerId { get; set; }
}

Support Foreign Key Attributes to specify Reference Fields​

Previously definitions of references relied on Reference Conventions using either the C# Property Name or Property Aliases. You can now also use the References and ForeignKey attributes to specify Reference Properties, e.g:

public class Customer
{
    [Reference(typeof(CustomerAddress))]
    public int PrimaryAddressId { get; set; }

    [Reference]
    public CustomerAddress PrimaryAddress { get; set; }
}

Reference Attributes take precedence over naming conventions

Support for Stored Procedures with out params​

A new SqlProc API was added returning an IDbCommand which can be used to customize the Stored Procedure call letting you add custom out parameters. The example below shows

string spSql = @"DROP PROCEDURE IF EXISTS spSearchLetters;
    CREATE PROCEDURE spSearchLetters (IN pLetter varchar(10), OUT pTotal int)
    BEGIN
        SELECT COUNT(*) FROM LetterFrequency WHERE Letter = pLetter INTO pTotal;
        SELECT * FROM LetterFrequency WHERE Letter = pLetter;
    END";

db.ExecuteSql(spSql);

var cmd = db.SqlProc("spSearchLetters", new { pLetter = "C" });
var pTotal = cmd.AddParam("pTotal", direction: ParameterDirection.Output);

var results = cmd.ConvertToList<LetterFrequency>();
var total = pTotal.Value;

An alternative approach is to use the new overload added to the raw SQL API SqlList that lets you customize the Stored Procedure using a filter, e.g:

IDbDataParameter pTotal = null;
var results = db.SqlList<LetterFrequency>("spSearchLetters", cmd => {
        cmd.CommandType = CommandType.StoredProcedure;
        cmd.AddParam("pLetter", "C");
        pTotal = cmd.AddParam("pTotal", direction: ParameterDirection.Output);
    });
var total = pTotal.Value;

Minor OrmLite Features​

• Use OrmLiteConfig.DisableColumnGuessFallback=false to disable fallback matching heuristics
• Added GenericTableExpressions example showing how to extend OrmLite to support different runtime table names on a single schema type.

AutoQuery​

Support for loading References​

AutoQuery now takes advantage of OrmLite's new support for loading child references where marking your Query DTO with [Reference] will automatically load its related data, e.g:

public class Rockstar
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }

    [Reference]
    public List<RockstarAlbum> Albums { get; set; } 
}

Improved OrderBy​

Add support for inverting sort direction of individual orderBy fields using '-' prefix e.g:

// ?orderBy=Rating,-ImdbId
var movies = client.Get(new SearchMovies { OrderBy = "Rating,-ImdbId" });

// ?orderByDesc=-Rating,ImdbId
var movies = client.Get(new SearchMovies { OrderByDesc = "-Rating,ImdbId" });

ServiceStack.Text​

• Added support for OrderedDictionary and other uncommon IDictionary types
• WCF-style JsConfig.OnSerializedFn custom hook has been added
• JsConfig.ReuseStringBuffer is enabled by default for faster JSON/JSV text serialization
• Properties can also be ignored with [JsonIgnore] attribute

Other Features​

• New [Exclude(Feature.Soap)] attribute can be used to exclude types from XSD/WSDL's
• XSD/WSDL's no longer including open generic types
• Added $.ss.getSelection(), $.ss.queryString(), $.ss.splitOnFirst(), $.ss.splitOnLast() to /ss-utils.js
• TwitterAuthProvider now makes authenticated v1.1 API requests to fetch user metadata