ES3 Common.js Add ServiceStack Reference

In addition to TypeScript support for generating typed Data Transfer Objects (DTOs), JavaScript is now supported.

Unlike TypeScript, JavaScript generated DTOs can be used directly from the browser, removing the need to keep your DTOs in sync with extra tooling by including a direct reference in your HTML Page:

<script src="/types/js"></script>

To make typed API Requests from web pages, you need only include:

  • /js/require.js - containing a simple require() to load CommonJS libraries
  • /js/servicestack-client.js - built-in UMD @servicestack/client in ServiceStack.dll
  • /types/js - containing your APIs typed JS DTOs - all built-in ServiceStack

After which you'll have access to the generic JsonServiceClient with your APIs Typed Request DTOs, e.g:

<script src="/js/require.js"></script>
<script src="/js/servicestack-client.js"></script>
<script src="/types/js"></script>

<script>
var { JsonServiceClient, Hello } = exports

var client = new JsonServiceClient()
client.api(new Hello({ name }))
    .then(api => console.log(api.response))
</script>

Using /types/js has the same behavior as using dtos.js generated from $ tsc dtos.ts whose outputs are identical, i.e. both containing your API DTOs generated in CommonJS format. It's feasible to simulate the TypeScript compiler's output in this instance as ServiceStack only needs to generate DTO Types and Enums to enable its end-to-end API, and not any other of TypeScript's vast feature set.

Enhanced Dev Time productivity with TypeScript​

Even when no longer using TypeScript DTOs in your Apps, it's still useful to have TypeScript's dtos.ts included in your project (inc. Vanilla JS projects) to serve as optional type annotations enabling rich intelli-sense and static analysis in IDEs that support it, but as it's no longer used at runtime you're free to generate it at optimal times that don't interrupt your dev workflow.

DTO Customization Options​

In most cases you'll just use the generated JavaScript DTO's as-is, however you can further customize how the DTOs are generated by overriding the default options.

The header in the generated DTOs show the different options JavaScript types support with their defaults. Default values are shown with the comment prefix of //. To override a value, remove the // and specify the value to the right of the :. Any uncommented value will be sent to the server to override any server defaults.

The DTO comments allows for customizations for how DTOs are generated. The default options that were used to generate the DTOs are repeated in the header comments of the generated DTOs, options that are preceded by a TypeScript comment // are defaults from the server, any uncommented value will be sent to the server to override any server defaults.

/* Options:
Date: 2022-01-28 02:10:26
Version: 6.00
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://vue-vite-api.jamstacks.net

//AddServiceStackTypes: True
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: 
*/

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

Change Default Server Configuration​

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

//Server example in CSharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.IgnoreTypesInNamespaces = "test";
...

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

IncludeTypes​

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

/* Options:
IncludeTypes: Hello, HelloResponse

Will only generate Hello and HelloResponse DTOs:

var HelloResponse = /** @class */ (function () {
    ...
}());
exports.HelloResponse = HelloResponse;
var Hello = /** @class */ (function () {
    ...
}());
exports.Hello = Hello;

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.

Cache​

When using /types/js directly from a script tag, the server will cache the result by default when not running in HostContext.DebugMode.

This caching process can be disabled if required by using ?cache=false.

Edit this page on GitHub