C# Add ServiceStack Reference

The primary and most popular Add ServiceStack Reference language supported is C#, providing a flexible alternative than sharing your DTO assembly with clients, now clients can easily add a reference to a remote ServiceStack instance and update DTO's directly from within VS.NET. This also lays the groundwork and signals our approach on adding support for typed API's in other languages in future. Add a feature request for your favorite language to prioritize support for it sooner!

Our goal with Native Types is to provide an alternative for sharing DTO dlls, that can enable a better dev workflow for external clients who are now able to generate (and update) Typed APIs for your Services from a remote url - reducing the burden and effort required to consume ServiceStack Services whilst benefiting from clients native language strong-typing feedback.

C# Xamarin.Android Example in VS.NET

Add ServiceStack Reference​

The easiest way to Add a ServiceStack reference to your project is to right-click on your project to bring up ServiceStackVS's Add ServiceStack Reference context-menu item. This opens a dialog where you can add the url of the ServiceStack instance you want to typed DTO's for, as well as the name of the DTO source file that's added to your project.

After clicking OK, the servers DTOs and ServiceStack.Client NuGet package are added to the project, providing an instant typed API:

With the C# code generated on the Server, the role of ServiceStackVS's Add ServiceStack Reference is then just to integrate the remote C# DTOs into the clients VS.NET project. This is just getting the generated DTOs from the server with default options set by the server and adding them locally to your project within Visual Studio.

Update ServiceStack Reference​

If your server has been updated and you want to update to client DTOs, simply right-click on the DTO file within VS.NET and select Update ServiceStack Reference.

Consuming Services from Mobile Clients​

Thanks to ServiceStack.Client PCL Support, it can also be used from within supported client platforms. Here's a quick Android demo of adding a ServiceStack reference to blazor-vue.web-templates.io and consuming one of StackApi's Services:

DTO Customization Options​

The header comments in the generated DTOs allows for further customization of how they're generated where ServiceStackVS automatically watches for any file changes and updates the generated DTOs with any custom Options provided. Options that are preceded by a C# single line comment // are defaults from the server that can be overridden, e.g:

/* Options:
Date: 2015-10-07 11:01:27
Version: 4.046
BaseUrl: https://blazor-vue.web-templates.io

//GlobalNamespace: 
//MakePartial: True
//MakeVirtual: True
//MakeDataContractsExtensible: False
//AddReturnMarker: True
//AddDescriptionAsComments: True
//AddDataContractAttributes: False
//AddIndexesToDataMembers: False
//AddGeneratedCodeAttributes: False
//AddResponseStatus: False
//AddImplicitVersion: 
//InitializeCollections: True
//IncludeTypes: 
//ExcludeTypes: 
//AddDefaultXmlNamespace: http://schemas.servicestack.net/types
*/

To override these options on the client, the // has to be removed. For example, if we did not want our classes to be partial by default for the C# client, our options would look like below:

/* Options:
Date: 2015-10-07 11:01:27
Version: 4.046
BaseUrl: https://blazor-vue.web-templates.io

//GlobalNamespace: 
MakePartial: False
//MakeVirtual: True
//MakeDataContractsExtensible: False
//AddReturnMarker: True
//AddDescriptionAsComments: True
//AddDataContractAttributes: False
//AddIndexesToDataMembers: False
//AddGeneratedCodeAttributes: False
//AddResponseStatus: False
//AddImplicitVersion: 
//InitializeCollections: True
//IncludeTypes: 
//ExcludeTypes: 
//AddDefaultXmlNamespace: http://schemas.servicestack.net/types
*/

Options that do not start with a // are sent to the server to override any defaults set by the server.

Change Default Server Configuration​

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the NativeTypesFeature Plugin, e.g:

var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.MakeVirtual = false;
...

Customize DTO Type generation​

Additional C# specific customization can be statically configured like PreTypeFilter, InnerTypeFilter & PostTypeFilter (available in all languages) can be used to inject custom code in the generated DTOs output.

Use the PreTypeFilter to generate source code before and after a Type definition, e.g. this will append the [Validate] attribute on non enum & interface types:

CSharpGenerator.PreTypeFilter = (sb, type) => {
    if (!type.IsEnum.GetValueOrDefault() && !type.IsInterface.GetValueOrDefault())
    {
        sb.AppendLine("[Validate]");
    }
};

The InnerTypeFilter gets invoked just after the Type Definition which can be used to generate common members for all Types and interfaces, e.g:

CSharpGenerator.InnerTypeFilter = (sb, type) => {
    sb.AppendLine("public string Id { get; } = Guid.NewGuid().ToString();");
};

There's also PrePropertyFilter & PostPropertyFilter for generating source before and after properties, e.g:

CSharpGenerator.PrePropertyFilter = (sb , prop, type) => {
    if (prop.Name == "Id")
    {
        sb.AppendLine("[PrimaryKey]");
    }
};

Emit custom code​

To enable greater flexibility when generating complex Typed DTOs, you can use [Emit{Language}] attributes to generate code before each type or property.

These attributes can be used to generate different attributes or annotations to enable client validation for different validation libraries in different languages, e.g:

[EmitCSharp("[Validate]")]
[EmitCode(Lang.CSharp | Lang.Swift | Lang.Dart, "// App User")]
public class User : IReturn<User>
{
    [EmitCSharp("[IsNotEmpty]","[IsEmail]")]
    [EmitCode(Lang.Swift | Lang.Dart, new[]{ "@isNotEmpty()", "@isEmail()" })]
    public string Email { get; set; }
}

Which will generate [EmitCsharp] code in C# DTOs:

[Validate]
// App User
public partial class User
    : IReturn<User>
{
    [IsNotEmpty]
    [IsEmail]
    public virtual string Email { get; set; }
}

Whilst the generic [EmitCode] attribute lets you emit the same code in multiple languages with the same syntax.

We'll go through and cover each of the above options to see how they affect the generated DTOs:

GlobalNamespace​

Specify which namespace the generated C# DTOs should use:

namespace Acme 
{
    //...
}

MakePartial​

Adds the partial modifier to all types, letting you extend generated DTOs with your own class separate from the generated types:

public partial class GetAnswers { ... }

MakeVirtual​

Adds the virtual modifier to all properties:

public partial class GetAnswers {
    ...
    public virtual int QuestionId { get; set; }
}

MakeDataContractsExtensible​

Add .NET's DataContract's ExtensionDataObject to all DTO's:

public partial class GetAnswers
    : IReturn<GetAnswerResponse>, IExtensibleDataObject
{
    ...
    public virtual ExtensionDataObject ExtensionData { get; set; }
}

AddReturnMarker​

When true, annotates Request DTOs with an IReturn<TResponse> marker referencing the Response type ServiceStack infers your Service to return:

public class GetAnswers
    : IReturn<GetAnswersResponse> { ... }

Original DTO doesn't require a return marker as response type can be inferred from Services return type or when using the %Response DTO Naming convention

AddDescriptionAsComments​

Converts any textual Description in [Description] attributes as C# Doc comments which allows your API to add intellisense in client projects:

///<summary>
///Get a list of Answers for a Question
///</summary>
public class GetAnswers { ... }

AddDataContractAttributes​

Decorates all DTO types with [DataContract] and properties with [DataMember] as well as adding default XML namespaces for all C# namespaces used:

[assembly: ContractNamespace("http://schemas.servicestack.net/types", 
           ClrNamespace="StackApis.ServiceModel.Types")]
[assembly: ContractNamespace("http://schemas.servicestack.net/types", 
           ClrNamespace="StackApis.ServiceModel")]
...

[DataContract]
public partial class GetAnswers
{
    [DataMember]
    public virtual int QuestionId { get; set; }
}

AddIndexesToDataMembers​

Populates a DataMember Order index for all properties:

[DataContract]
public partial class GetAnswers
{
    [DataMember(Order=1)]
    public virtual int QuestionId { get; set; }
}

Requires AddDataContractAttributes=true

AddGeneratedCodeAttributes​

Emit [GeneratedCode] attribute on all generated Types:

[GeneratedCode]
public partial class GetAnswers { ... }

AddResponseStatus​

Automatically add a ResponseStatus property on all Response DTOs, regardless if it wasn't already defined:

public class GetAnswersResponse
{
    ...
    public ResponseStatus ResponseStatus { get; set; }
}

AddImplicitVersion​

Usage:

/* Options:
AddImplicitVersion: 1

Lets you specify the Version number to be automatically populated in all Request DTOs sent from the client:

public partial class GetAnswers
    : IReturn<GetAnswersResponse>
{
    public virtual int Version { get; set; }

    public GetAnswers()
    {
        Version = 1;
    }
    ...
}

This lets you know what Version of the Service Contract that existing clients are using making it easy to implement ServiceStack's recommended versioning strategy.

InitializeCollections​

Usage:

/* Options:
InitializeCollections: True

Lets you automatically initialize collections in Request DTOs:

public class SearchQuestions
{
    public SearchQuestions()
    {
        Tags = new List<string>{};
    }

    public List<string> Tags { get; set; }
    ...
}

Initialized collections lets you take advantage of C#'s collection initializers for a nicer client API:

var response = client.Get(new SearchQuestions { 
    Tags = { "redis", "ormlite" }
});

IncludeTypes​

Is used as a Whitelist to specify only the types you would like to have code-generated:

/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse

Will only generate GetTechnology and GetTechnologyResponse DTO's:

public class GetTechnology { ... }
public class GetTechnologyResponse { ... }

Include Generic Types​

Use .NET's Type Name to include Generic Types, i.e. the Type name separated by the backtick followed by the number of generic arguments, e.g:

IncludeTypes: IReturn`1,MyPair`2

Include Request DTO and its dependent types​

You can include a Request DTO and all its dependent types with a .* suffix on the Request DTO, e.g:

/* Options:
IncludeTypes: GetTechnology.*

Which will include the GetTechnology Request DTO, the GetTechnologyResponse Response DTO and all Types that they both reference.

Include All Types within a C# namespace​

If your DTOs are grouped into different namespaces they can be all included using the /* suffix, e.g:

/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*

This will include all DTOs within the MyApp.ServiceModel.Admin C# namespace.

Include All Services in a Tag Group​

Services grouped by Tag can be used in the IncludeTypes where tags can be specified using braces in the format {tag} or {tag1,tag2,tag3}, e.g:

/* Options:
IncludeTypes: {web,mobile}

Or individually:

/* Options:
IncludeTypes: {web},{mobile}

ExcludeTypes​

Is used as a Blacklist to specify which types you would like excluded from being generated:

/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse

Will exclude GetTechnology and GetTechnologyResponse DTOs from being generated.

AddNamespaces​

Include additional C# namespaces, e.g:

/* Options:
AddNamespaces: System.Drawing,MyApp

Where it will generate the specified namespaces in the generated Types:

using System.Drawing;
using MyApp;

AddDefaultXmlNamespace​

This lets you change the default DataContract XML namespace used for all C# namespaces:

[assembly: ContractNamespace("http://my.types.net", 
           ClrNamespace="StackApis.ServiceModel.Types")]
[assembly: ContractNamespace("http://my.types.net", 
           ClrNamespace="StackApis.ServiceModel")]

Requires AddDataContractAttributes=true

Xamarin Studio​

With the new ServiceStackXS Add-In your Service Consumers can now generate typed DTOs of your remote ServiceStack Services directly from within Xamarin Studio, which together with the ServiceStack.Client NuGet package provides an effortless way to enable an end-to-end Typed API from within Xamarin C# projects.

Installing ServiceStackXS​

Installation is straightforward if you've installed Xamarin Add-ins before, just go to Xamarin Studio -> Add-In Manager... from the Menu and then search for ServiceStack from the Gallery:

Install from file​

If you are having trouble with the Xamarin Studio gallery version, you can install addins from an mpack file from the same menu as shown above. Click Install from file and navigate to where you have downloaded the mpack file.

Adding a ServiceStack Reference​

Once installed, adding a ServiceStack Reference is very similar to ServiceStackVS in VS.NET where you can just click on Add -> Add ServiceStack Reference... on the project's context menu to bring up the familiar Add Reference dialog. After adding the BaseUrl of the remote ServiceStack instance, click OK to add the generated DTO's to your project using the name specified:

Updating the ServiceStack Reference​

As file watching isn't supported yet, to refresh the generated DTOs, you'll need to right-click on it in the solution explorer and select Update ServiceStack Reference from the items context menu.

Xamarin Studio for Linux​

One of the nice benefits of creating an Xamarin Studio Add-in is that we're also able to bring the same experience to .NET Developers on Linux! Which works similar to OSX where you can install ServiceStackXS from the Add-in Gallery - Here's an example using Ubuntu:

Then Add ServiceStack Reference is accessible in the same way: