Plugins

As of v3.55 ServiceStack introduces a new Plugin API that all of ServiceStack add-ons now implement:

Plugin API

public interface IPlugin
{
    void Register(IAppHost appHost);
}

If your plugin also implements IPreInitPlugin it will get run before any plugins are registered:

public interface IPreInitPlugin
{
    void Configure(IAppHost appHost);
}

All built-in Plugins are Registered and available via base.Plugins before your Configure() script is run so you have a chance to modify the behaviour or remove un-used plugins which is exactly what the short-hand:

SetConfig(new EndpointHostConfig { 
    EnableFeatures = Features.All.Remove(Features.Csv)
});

Which under the covers just does:

if ((Feature.Csv & config.EnableFeatures) != Feature.Csv)
	Plugins.RemoveAll(x => x is CsvFormat);

Which you now also have an opportunity to also do in your AppHost Configure() start-up script yourself - if you want to remove or customize any pre-loaded plugins.

You can easily use LINQ to fetch any specific plugin:

var htmlFormat = (HtmlFormat)base.Plugins.First(x => x is HtmlFormat);

List of Plugins added by Default

A list of all of the plugins available on ServiceStack and how to add them:

Auto-registered plugins

These plugins below are already added by default, you can remove or customize them using the methods described above.

Metadata Feature

Provides ServiceStack's auto-generated metadata pages.

var feature = Plugins.FirstOrDefault(x => x is MetadataFeature); 
Plugins.RemoveAll(x => x is MetadataFeature); 

Predefined Routes

Provides ServiceStack's pre-defined routes used in the built-in C# Service Clients.

var feature = Plugins.FirstOrDefault(x => x is PredefinedRoutesFeature); 
Plugins.RemoveAll(x => x is PredefinedRoutesFeature); 

Request Info

Provides ServiceStack's Request Info feature useful for debugging requests. Just add _requestinfo in your /pathinfo and ServiceStack will return a dump of all the HTTP Request parameters to help with with debugging interoperability issues. The RequestInfoFeature is only enabled for Debug builds.

var feature = Plugins.FirstOrDefault(x => x is RequestInfoFeature); 
Plugins.RemoveAll(x => x is RequestInfoFeature); 

CSV Format

Providing ServiceStack's CSV Format.

var feature = Plugins.FirstOrDefault(x => x is CsvFormat); 
Plugins.RemoveAll(x => x is CsvFormat); 

Note: By default the CSV Format tries serialize the Response object directly into CSV which is only ideal if your responses return List<Poco>. If however you mark your Response DTO with the [Csv(CsvBehavior.FirstEnumerable)] attribute the CSV Format instead will only serialize the first IEnumerable<T> it finds on your Response DTO e.g. if you had a List<Poco> Results property it will only serialize this list in the tabular CSV Format which is typically the behaviour you want.

Html Format

Providing ServiceStack's Html Format.

var feature = Plugins.FirstOrDefault(x => x is HtmlFormat); 
Plugins.RemoveAll(x => x is HtmlFormat); 

Razor Markdown Format

This provides ServiceStack's Razor Markdown Format and also enables ServiceStack to serve static .md or .markdown files in either plain text, rendered as HTML (partial), or rendered in HTML inside a static _Layout.shtml HTML template.

var feature = Plugins.FirstOrDefault(x => x is MarkdownFormat); 
Plugins.RemoveAll(x => x is MarkdownFormat); 

The entire www.servicestack.net/docs website is rendered using static Markdown. More information of Razor Markdown features can be found in:

• Introduction to Markdown Razor
• Mardown Razor Features
• How Docs is built with Markdown

Available Plugins

The rest of ServiceStack's plugins are not enabled by default by can easily be added on adhoc basis, as and when needed.

Swagger support

Swagger support an optional add-on available in the ServiceStack.Api.Swagger NuGet package.

After installing the NuGet package enable the Swagger with:

Plugins.Add(new SwaggerFeature());

Now you can enjoy your shiny new Swagger UI at: http://yoursite/swagger-ui/index.html

Annotating your services

You can further document your services in the Swagger UI with the new [Api] and [ApiMember] annotation attributes, e,g: Here's an example of a fully documented service:

[Api("Service Description")]
[Route("/swagger/{Name}", "GET", Summary = @"GET Summary", Notes = "GET Notes")]
[Route("/swagger/{Name}", "POST", Summary = @"POST Summary", Notes = "POST Notes")]
public class MyRequestDto
{
    [ApiMember(Name="Name", Description = "Name Description", 
               ParameterType = "path", DataType = "string", IsRequired = true)]
    public string Name { get; set; }
}

Razor Format

Provides ServiceStack's primary HTML story with support for the MVC Razor view engine.

Plugins.Add(new RazorFormat()); 

It's an optional .NET 4.0 plugin that is available in the ServiceStack.Razor NuGet package.

Validation

Enable the validation feature if you want to ensure all of ServiceStack's Fluent validators for Request DTOs IValidator<TRequestDto> are automatically validated on every request.

Plugins.Add(new ValidationFeature());

More information on ServiceStack's built-in Fluent Validation support is described on the Validation page.

Authentication

The Authentication Feature enables the Authentication and Authorization support in ServiceStack. It makes available the AuthService at the default route at /auth/{provider}, registers AssignRoles and UnAssignRoles services (at /assignroles and /unassignroles default routes) and auto-enables Session support if it's not added already.

An example AuthFeature registration (taken from the SocialBootstrapApi project):

Plugins.Add(new AuthFeature(
	() => new CustomUserSession(), //Use your own typed Custom UserSession type
	new IAuthProvider[] {
	    new CredentialsAuthProvider(),         //HTML Form post of UserName/Password credentials
	    new TwitterAuthProvider(appSettings),  //Sign-in with Twitter
	    new FacebookAuthProvider(appSettings), //Sign-in with Facebook
	    new BasicAuthProvider(),               //Sign-in with Basic Auth
	}));

This registers and provides your ServiceStack host a myriad of different Authentication options as described above.

Session support

If you're not using the AuthFeature above and you still want Session support you need to enable it explicitly with:

Plugins.Add(new SessionFeature());

This will add a Request Filter to instruct any HTTP client calling a ServiceStack web service to create a Temporary (ss-id) and Permanent (ss-pid) cookie if not already done so.

Registration

Related to Authentication is Registration which enables the Registration Service at the default route /register which lets new Users to be registered and validated with the Credentials and Basic AuthProviders.

Plugins.Add(new RegistrationFeature());

See the SocialBootstrapApi project for a working example of Registration and Authentication.

MessagePack format

To add fast binary MessagePack support to ServiceStack install the ServiceStack.Plugins.MsgPack NuGet package and register the plugin with:

Plugins.Add(new MsgPackFormat());

ProtoBuf format

To enable ProtoBuf support install the ServiceStack.Plugins.ProtoBuf NuGet package and register the plugin with:

Plugins.Add(new ProtoBufFormat());

Request Logger

Add an In-Memory IRequestLogger and service with the default route at /requestlogs which maintains a live log of the most recent requests (and their responses). Supports multiple config options incl. Rolling-size capacity, error and session tracking, hidden request bodies for sensitive services, etc.

Plugins.Add(new RequestLogsFeature());

The IRequestLogger is a great way to introspect and analyze your service requests in real-time. Here's a screenshot from the http://bootstrapapi.apphb.com website:

It supports multiple queryString filters and switches so you filter out related requests for better analysis and debuggability:

The RequestLogsService is just a simple C# service under-the-hood but is a good example of how a little bit of code can provide a lot of value in ServiceStack's by leveraging its generic, built-in features.

Community Resources

• Extending ServiceStack by morganskinner