C# client

Using DTOs to define your web service interface makes it possible to provide strong-typed generic service clients without any code-gen or extra build-steps, leading to a productive end-to-end type-safe communication gateway from client to server.

REST API

All ServiceStack's C# clients share the same interfaces and are created by passing in the Base URI of your ServiceStack service in the clients constructor, e.g. if your ServiceStack instance was hosted on the root path / on the 8080 custom port:

var client = new JsonServiceClient("http://host:8080/");

Or if hosted on the /api custom path:

var client = new JsonServiceClient("http://host/api/");

In addition, the service clients also provide HTTP verbs (Get, Post & PostFile, Put, Delete) letting you call your custom user-defined routes REST-fully e.g:

Using the New Api

HelloResponse response = client.Get(new Hello { Name = "World!" });
response.Result.Print();

Async Example

client.GetAsync(new Hello { Name = "World!" },
    r => r.Result.Print(), (r, ex) => { throw ex; });

Alternative API

var response = client.Get<HelloResponse>("/hello/World!");
response.Result.Print();

Async Example

client.GetAsync<HelloResponse>("/hello/World!",
    r => r.Result.Print(), (r, ex) => { throw ex; });

---

Service Client API

C#/.NET Clients can call the above Hello Service using any of the JSON, JSV, XML or SOAP Service Clients with the code below:

Using the New Api

var response = client.Send(new Hello { Name = "World!" });
response.Result.Print();

Async Example

client.SendAsync(new Hello { Name = "World!" },
    r => r.Result.Print(), (r, ex) => { throw ex; });

Alternative API

var response = client.Send<HelloResponse>(new Hello { Name = "World!" });
response.Result.Print();

Async Example

client.SendAsync<HelloResponse>(new Hello { Name = "World!" },
    r => r.Result.Print(), (r, ex) => { throw ex; });

The service clients use the automatic pre-defined routes for each service.

Authentication

ServiceStack's Auth Tests shows different ways of authenticating when using the C# Service Clients. By default BasicAuth and DigestAuth is built into the clients, e.g:

var client = new JsonServiceClient(baseUri) {
    UserName = UserName,
    Password = Password,
};

var request = new Secured { Name = "test" };
var response = client.Send<SecureResponse>(request);    

Behind the scenes ServiceStack will attempt to send the request normally but when the request is rejected and challenged by the Server the clients will automatically retry the same request but this time with the Basic/Digest Auth headers.

To skip the extra hop when you know you're accessing a secure service, you can tell the clients to always send the BasicAuth header with:

client.AlwaysSendBasicAuthHeader = true;

The alternative way to Authenticate is to make an explicit call to the Auth service (this requires CredentialsAuthProvider enabled) e.g:

AuthResponse authResponse = client.Post(new Auth {
    provider = CredentialsAuthProvider.Name,
    UserName = "user",
    Password = "p@55word",
    RememberMe = true,  //important tell client to retain permanent cookies
});

var request = new Secured { Name = "test" };
var response = client.Send<SecureResponse>(request);    

After a successful call to the Auth service the client is Authenticated and if RememberMe is set, the client will retain the Session Cookies added by the Server on subsequent requests which is what enables future requests from that client to be authenticated.

---

Built-in Clients

All REST and ServiceClients share the same interfaces (IServiceClient, IRestClient and IRestClientAsync) so they can easily be replaced (for increased perf/debuggability/etc) with a single line of code.

Here's a list of all built-in clients:

• implements both IRestClient and IServiceClient:
  • JsonServiceClient (uses default endpoint with JSON) - recommended
  • JsvServiceClient (uses default endpoint with JSV)
  • XmlServiceClient (uses default endpoint with XML)
  • MsgPackServiceClient (uses default endpoint with Message-Pack)
  • ProtoBufServiceClient (uses default endpoint with Protocol Buffers)
• implements IServiceClient only:
  • Soap11ServiceClient (uses SOAP 11 endpoint)
  • Soap12ServiceClient (uses SOAP 12 endpoint)