CSharp 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.
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.
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.
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:
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
//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: http://stackapis.servicestack.net
//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.
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
%ResponseDTO Naming convention
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 { ... }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; }
}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
Emit [GeneratedCode] attribute on all generated Types:
[GeneratedCode]
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.
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" }
});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",
ClrNamespace="StackApis.ServiceModel.Types")]
[assembly: ContractNamespace("http://my.types.net",
ClrNamespace="StackApis.ServiceModel")]Requires AddDataContractAttributes=true
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.
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:
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.
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:
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.
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:
