CSharp Add ServiceStack Reference

Demis Bellot edited this page Oct 25, 2016 · 10 revisions

This page has moved to docs.servicestack.net

C# Platforms

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.

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.

Add ServiceStack Reference

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

Calling ServiceStack Service

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.

Add CSharp ServiceStack Reference Demo

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.

CSharp update demo

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 stackapis.servicestack.net and consuming one of StackApi's Services:

Android Add ServiceStack Reference

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: http://stackapis.servicestack.net

//MakePartial: True
//MakeVirtual: True
//MakeDataContractsExtensible: False
//AddReturnMarker: True
//AddDescriptionAsComments: True
//AddDataContractAttributes: False
//AddIndexesToDataMembers: False
//AddGeneratedCodeAttributes: False
//AddResponseStatus: False
//InitializeCollections: True
//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: http://stackapis.servicestack.net

MakePartial: False
//MakeVirtual: True
//MakeDataContractsExtensible: False
//AddReturnMarker: True
//AddDescriptionAsComments: True
//AddDataContractAttributes: False
//AddIndexesToDataMembers: False
//AddGeneratedCodeAttributes: False
//AddResponseStatus: False
//InitializeCollections: True
//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;

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


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 { ... }


Adds the virtual modifier to all properties:

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


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

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


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


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

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


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", 
[assembly: ContractNamespace("http://schemas.servicestack.net/types", 

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


Populates a DataMember Order index for all properties:

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

Requires AddDataContractAttributes=true


Emit [GeneratedCode] attribute on all generated Types:

public partial class GetAnswers { ... }


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

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


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.



/* 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" }


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 { ... }


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.


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

[assembly: ContractNamespace("http://my.types.net", 
[assembly: ContractNamespace("http://my.types.net", 

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:

  1. Getting Started

    1. Creating your first project
    2. Create Service from scratch
    3. Your first webservice explained
    4. Example Projects Overview
    5. Learning Resources
  2. Designing APIs

    1. ServiceStack API Design
    2. Designing a REST-ful service with ServiceStack
    3. Simple Customer REST Example
    4. How to design a Message-Based API
    5. Software complexity and role of DTOs
  3. Reference

    1. Order of Operations
    2. The IoC container
    3. Configuration and AppSettings
    4. Metadata page
    5. Rest, SOAP & default endpoints
    6. SOAP support
    7. Routing
    8. Service return types
    9. Customize HTTP Responses
    10. Customize JSON Responses
    11. Plugins
    12. Validation
    13. Error Handling
    14. Security
    15. Debugging
    16. JavaScript Client Library (ss-utils.js)
  4. Clients

    1. Overview
    2. C#/.NET client
      1. .NET Core Clients
    3. Add ServiceStack Reference
      1. C# Add Reference
      2. F# Add Reference
      3. VB.NET Add Reference
      4. Swift Add Reference
      5. Java Add Reference
    4. Silverlight client
    5. JavaScript client
      1. Add TypeScript Reference
    6. Dart Client
    7. MQ Clients
  5. Formats

    1. Overview
    2. JSON/JSV and XML
    3. HTML5 Report Format
    4. CSV Format
    5. MessagePack Format
    6. ProtoBuf Format
  6. View Engines 4. Razor & Markdown Razor

    1. Markdown Razor
  7. Hosts

    1. IIS
    2. Self-hosting
    3. Messaging
    4. Mono
  8. Security

    1. Authentication
    2. Sessions
    3. Restricting Services
    4. Encrypted Messaging
  9. Advanced

    1. Configuration options
    2. Access HTTP specific features in services
    3. Logging
    4. Serialization/deserialization
    5. Request/response filters
    6. Filter attributes
    7. Concurrency Model
    8. Built-in profiling
    9. Form Hijacking Prevention
    10. Auto-Mapping
    11. HTTP Utils
    12. Dump Utils
    13. Virtual File System
    14. Config API
    15. Physical Project Structure
    16. Modularizing Services
    17. MVC Integration
    18. ServiceStack Integration
    19. Embedded Native Desktop Apps
    20. Auto Batched Requests
    21. Versioning
    22. Multitenancy
  10. Caching

  11. Caching Providers

  12. HTTP Caching

  13. CacheResponse Attribute

  14. Cache Aware Clients

  15. Auto Query

  16. Overview

  17. Why Not OData

  18. AutoQuery RDBMS

  19. AutoQuery Data

  20. AutoQuery Memory

  21. AutoQuery Service

  22. AutoQuery DynamoDB

  23. Server Events

    1. Overview
    2. JavaScript Client
    3. C# Server Events Client
    4. Redis Server Events
  24. Service Gateway

    1. Overview
    2. Service Discovery
  25. Encrypted Messaging

    1. Overview
    2. Encrypted Client
  26. Plugins

    1. Auto Query
    2. Server Sent Events
    3. Swagger API
    4. Postman
    5. Request logger
    6. Sitemaps
    7. Cancellable Requests
    8. CorsFeature
  27. Tests

    1. Testing
    2. HowTo write unit/integration tests
  28. ServiceStackVS

    1. Install ServiceStackVS
    2. Add ServiceStack Reference
    3. TypeScript React Template
    4. React, Redux Chat App
    5. AngularJS App Template
    6. React Desktop Apps
  29. Other Languages

    1. FSharp
      1. Add ServiceStack Reference
    2. VB.NET
      1. Add ServiceStack Reference
    3. Swift
    4. Swift Add Reference
    5. Java
      1. Add ServiceStack Reference
      2. Android Studio & IntelliJ
      3. Eclipse
  30. Amazon Web Services

  31. ServiceStack.Aws

  32. PocoDynamo

  33. AWS Live Demos

  34. Getting Started with AWS

  35. Deployment

    1. Deploy Multiple Sites to single AWS Instance
      1. Simple Deployments to AWS with WebDeploy
    2. Advanced Deployments with OctopusDeploy
  36. Install 3rd Party Products

    1. Redis on Windows
    2. RabbitMQ on Windows
  37. Use Cases

    1. Single Page Apps
    2. HTML, CSS and JS Minifiers
    3. Azure
    4. Connecting to Azure Redis via SSL
    5. Logging
    6. Bundling and Minification
    7. NHibernate
  38. Performance

    1. Real world performance
  39. Other Products

    1. ServiceStack.Redis
    2. ServiceStack.OrmLite
    3. ServiceStack.Text
  40. Future

    1. Roadmap
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.