@servicestack/cli

Simple command-line utilities for ServiceStack

The @servicestack/cli provides simple command-line utilities to easily Add and Update ServiceStack References for all of ServiceStack's supported languages:

Supported Languages

• C# Add ServiceStack Reference
• TypeScript Add ServiceStack Reference
• Swift Add ServiceStack Reference
• Java Add ServiceStack Reference
• Kotlin Add ServiceStack Reference
• VB.NET Add ServiceStack Reference
• F# Add ServiceStack Reference

Installation

Prerequisites: Node.js (>=4.x, 6.x preferred), npm version 3+.

$ npm install -g @servicestack/cli

This will make the following utilities availble from your command-line which will let you download the Server DTO classes for a remote ServiceStack endpoint in your chosen language which you can use with ServiceStack's generic Service clients to be able to make end-to-end API calls.

| Script | Alias | Language | | ------ | ----- | -------- | | csharp-ref | cs-ref | C# | | typescript-ref | ts-ref | TypeScript | | typescriptd-ref | tsd-ref | TypeScript Declarations | | swift-ref | | Swift | | java-ref | | Java | | kotlin-ref | kt-ref | Kotlin | | vbnet-ref | vb-ref | VB.NET | | fsharp-ref | fs-ref | F# |

Usage

We'll walkthrough an example using TypeScript to download Server Types from the techstacks.io ServiceStack Website to see how this works:

Adding a ServiceStack Reference

To Add a TypeScript ServiceStack Reference just call typescript-ref with the URL of a remote ServiceStack instance:

$ typescript-ref http://techstacks.io

Result:

Saved to: techstacks.dtos.ts

Calling typescript-ref with just a URL will save the DTOs using the Host name, you can override this by specifying a FileName as the 2nd argument:

$ typescript-ref http://techstacks.io Tech

Result:

Saved to: Tech.dtos.ts

Updating a ServiceStack Reference

To Update an existing ServiceStack Reference, call typescript-ref with the Filename:

$ typescript-ref techstacks.dtos.ts

Result:

Updated: techstacks.dtos.ts

Which will update the File with the latest TypeScript Server DTOs from techstacks.io. You can also customize how DTOs are generated by uncommenting the TypeScript DTO Customization Options and updating them again.

Updating all TypeScript DTOs

Calling typescript-ref without any arguments will update all TypeScript DTOs in the current directory:

$ typescript-ref

Result:

Updated: Tech.dtos.ts
Updated: techstacks.dtos.ts

To make it more wrist-friendly you can also use the shorter ts-ref alias instead of typescript-ref.

Installing Generic Service Client

Now we have our TechStacks Server DTOs we can use them with the generic JsonServiceClient in the @servicestack/client npm package to make Typed API Calls.

Install @servicestack/client

$ npm install @servicestack/client

TechStacks Example

Once installed create a demo.ts file with the example below using both the JsonServiceClient from the @servicestack/client npm package and the Server DTOs we want to use from our local techstacks.dtos.ts above:

import { JsonServiceClient } from '@servicestack/client';
import { GetTechnology, GetTechnologyResponse } from './techstacks.dtos';

var client = new JsonServiceClient("http://techstacks.io")

let request = new GetTechnology()
request.Slug = "ServiceStack"

client.get(request)
    .then(r => console.log(r.Technology.VendorUrl))

The JsonServiceClient is populated with the BaseUrl of the remote ServiceStack instance we wish to call. Once initialized we can send populated Request DTOs and handle the Typed Response DTOs in Promise callbacks.

To run our TypeScript example we just need to compile it with TypeScript:

$ tsc demo.ts

Which will generate the compiled demo.js (and typescript.dtos.js) which we can then run with node:

$ node demo.js

Result:

https://servicestack.net

Enabling TypeScript async/await

To make API requests using TypeScript's async/await feature we'll need to create a TypeScript tsconfig.json config file that imports ES6 promises and W3C fetch definitions with:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "lib": [ "es2015", "dom" ]
  }
}

Now we can create a new await-demo.ts file and start using TypeScript's async/await feature which as it can only be called within an async function, we'll need to wrap in an async function:

import { JsonServiceClient } from '@servicestack/client';
import { GetTechnology, GetTechnologyResponse } from './techstacks.dtos';

var client = new JsonServiceClient("http://techstacks.io")

async function main() {
    let request = new GetTechnology()
    request.Slug = "ServiceStack"

    const response = await client.get(request)
    console.log(response.Technology.VendorUrl)
}

main()

Now that we have a tsconfig.json we can just call tsc to compile all our TypeScript source files in our folder:

$ tsc

And then run the compiled await-demo.js with node:

$ node await-demo.js

Result:

https://servicestack.net