Skip to content

Home

Jump to bottom
fonlow edited this page Jun 5, 2017 · 14 revisions

Strongly Typed Client API Generators generate strongly typed client API in C# codes and TypeScript codes. You may then provide or publish either the generated source codes or the compiled client API libraries to other developers for developing client programs.

This project delivers these products:

  1. Code generator for strongly typed client API in C# supporting desktop, Universal Windows, Android and iOS.
  2. Code generator for strongly typed client API in TypeScript for jQuery and Angular 2.
  3. TypeScript CodeDOM, a CodeDOM component for TypeScript, derived from CodeDOM of .NET Framework.
  4. POCO2TS.exe, a command line program that generates TypsScript interfaces from POCO classes.
  5. Fonlow.Poco2Ts, a component that generates TypsScript interfaces from POCO classes

Examples

  1. POCO classes
  2. Web API
  3. Generated client API C# codes
  4. Client codes using the generated library in C#
  5. Generated client data models and API in TypeScript for jQuery and for Angular 2
  6. Client codes using the generated library in TypeScript

Concepts

  1. Web API vendors / developers should provide client API libraries to developers of client programs, as Google and Amazon etc. would do in order to make the RESTful Web API reach wider consumers (internal and external) efficiently.
  2. To client developers, classic function prototypes like ReturnType DoSomething(Type1 t1, Type2 t2 ...) is the API function, and the rest is the technical implementation details of transportations: TCP/IP, HTTP, SOAP, resource-oriented, CRUD-based URIs, RESTful, XML and JSON etc. The function prototype and a piece of API document should be good enough for calling the API function.
  3. The better you have separation of concerns in your Web API design, the more you will benefit from the components of this project in order to deliver business values sooner, with less handcraft codes , less repetitive tasks and less chances of human mistakes.

Getting Started

Presumptions

  1. You are developing ASP.NET Web API 2.x applications, and the client programs of the APIs include Windows desktop applications and Windows store apps, in addition to the Web front end based on AJAX.
  2. Many of the API functions are to transport DTO in content type application/json or application/xml.
  3. You and fellow developer prefer highly abstraction through strongly typed functions in both the server side and the client side.
  4. You expect that the client API generated has the same level of abstraction and strongly typed functions like those generated by SvcUtil.exe in WCF.
  5. The POCO classes are used by both Web API and Entity Framework Code First, and you may not want to publish all data members to client programs.

Optional Presumptions

This component set was designed for big projects with large amount of complex data models and rich Web API, thus certain engineering best practices are expected.

  1. You have some experiences in developing or consuming SOAP Web services through WCF, and you know about DataCotractAttribute.
  2. Your Web application is big enough so you would put most if not all data models (POCO classes) into 1 or 2 dedicated assemblies besides the MVC or Web API assembly.
  3. You would use data annotations for defining DTO (Data Transfer Object) from existing data model classes.

Hints: Even if your design does not fall into the optional presumptions, for example, having all classes into the MVC/Web API project, you may still use this component set well.

What's Not

In these scenarios, the code generators may not be for you:

  1. Your Web API is for AJAX Web applications which do not use TypeScript during development, even though the javascript files compiled from the generated TypeScript codes are usable in traditional Javascript development.
  2. You bill through LoC or hours and you don't mind doing repetitive tasks of constructing client codes.
  3. Your Web API functions are not strongly typed in the function prototypes, for example dealing with only IHttpActionResult, documents and stream.
  4. You want the client programming cares more about or take advantages of REST or "Hypermedia as The Engine of Application State" (HATEOAS) because your domains may be better to be presented as resources and states.

Remarks: Even if you decide to go the HATEOAS path, the POCO2TS application may generate TypeScript interfaces to describe the data models. Including TypeScript interfaces may help the consumers of your HAL services.

Prerequisites

Server side:

  1. .NET Framework 4.5.2
  2. ASP.NET Web API 2.2

.NET client side:

  1. .NET Framework 4.5, or Universal Windows, or Mono.Android, or Xamarin.iOS
  2. ASP.NET Web API 2.2 Client Libraries
  3. Json.NET of Newtonsoft for Content-Type application/json
  4. Microsoft Build Tools 2015

TypeScript client side:

  1. TypeScript compiler
  2. jQuery
  3. Angular 2/4 and its dependencies in node_modules supported by Node.js and npm.

For more details, please check DOCUMENTATION.

Clone this wiki locally