Skip to content

Getting Started

Jump to bottom
fonlow edited this page May 20, 2018 · 28 revisions

Before Getting Started

All custom complex types exposed in the API should be decorated by DataContractAttribute or JsonObjectAttribute, unless you want opt-out approaches of cherry-picking.

For .NET Client API

The service CLR namespaces will be translated to client namespaces through appending ".Client" as suffix. For example, namespace My.Name.space will be translated to {"My.Name.space.Client"}.

For TypeScript Client API

While ASP.NET MVC and Web API use NewtonSoft.Json for JSON applications, NewtonSoft.Json can handle well POCO classes decorated by DataContractAttribute.

The CLR namespaces will be translated to TypeScript namespaces through replacing dot with underscore and adding "Client" as suffix. For example, namespace My.Name.space will be translated to {"My_Name_space_Client"}.

Enable Doc Comments of Web API

In C:\YourWebSlnPath\Your.WebApi\Areas\HelpPage\App_Start\HelpPageConfig.cs, there is such line:

//config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Uncomment it and make it be like this:

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/Your.WebApi.xml")));

In the Build tab of the project Properties page, check Output/XML Document File and set "bin\Your.WebApi.xml", while the the output path is "bin" by default.

If you have other assemblies for data models, you may do the same to ensure doc comments to be generated and copied over to the client API.

Remarks

In the .NET Core build of WebApiClientGen, this step is irrelevant. The toolkit will import from the XML document of the .NET Core Web API assembly directly.

Getting Started

Step 0: Install NuGet package WebApiClientGen to the Web MVC/API project.

The installation will also install dependent NuGet packages Fonlow.TypeScriptCodeDOM and Fonlow.Poco2Ts to the project references.

The NuGet package will add 2 TS files to the ~/Scripts/ClientApi folder of the project, one is HttpClient.ts, and the other is WebApiClientAuto.ts which will be replaced everytime the CodeGen is triggered.

Additionally, CodeGenController.cs is added to the project's Controllers folder.

#if DEBUG  //This controller is not needed in production release, since the client API should be generated during development of the Web Api.
...

namespace Fonlow.WebApiClientGen
{
    [System.Web.Http.Description.ApiExplorerSettings(IgnoreApi = true)](System.Web.Http.Description.ApiExplorerSettings(IgnoreApi-=-true))//this controller is a dev backdoor during development, no need to be visible in ApiExplorer.
    public class CodeGenController : ApiController
    {
        /// <summary>
        /// Trigger the API to generate WebApiClientAuto.cs for an established client API project.
        /// POST to  http://localhost:10965/api/CodeGen with json object CodeGenParameters
        /// </summary>
        /// <param name="parameters"></param>
        /// <returns>OK if OK</returns>
        [HttpPost](HttpPost)
        public string TriggerCodeGen(CodeGenParameters parameters)
        {
...
        }
    }

The CodeGenController should be available only during development in the debug build, since the client API should be generated once for each version of the Web API.

Remarks

CodeGenController is installed in YourMvcOrWebApiProject/Controllers, even though the scaffolding of a MVC project has folder API for derived classes of ApiController.

Step 1: Create the .NET client API project (optional)

This step is not needed if you don't expect any client program coded on .NET Framework.

Ensure the following packages are referenced:

  1. Microsoft ASP.NET Web API 2.2 Client Libraries
  2. Json.NET which is introduced through the first one by default.
  3. System.Runtime.Serialization
  4. System.ServiceModel
  5. System.ComponentModel.DataAnnotations

Step 2: Run the DEBUG build of the Web API project to trigger the generation of client API codes

Run the Web project in IDE with IIS Express. You have options of generating TypeScript client API codes, or C# client API codes, or both.

You then use Curl or Poster or any of your favorite client tools to POST to http://localhost:10965/api/CodeGen, with content-type=application/json

{
    "ApiSelections": {
        "ExcludedControllerNames": [
            "DemoWebApi.Controllers.Account"
        ],

        "DataModelAssemblyNames": [
            "DemoWebApi.DemoData",
            "DemoWebApi"
        ],
        "CherryPickingMethods": 1
    },

    "ClientApiOutputs": {
        "ClientLibraryProjectFolderName": "DemoWebApi.ClientApi",
        "GenerateBothAsyncAndSync": true,

        "CamelCase": true,
        "TypeScriptJQFolder": "Scripts\\ClientApi",
        "TypeScriptNG2Folder": "..\\DemoAngular2\\ClientApi",
        "NGVersion" : 5.0
    }
}

If ClientLibraryProjectFolderName is not defined, no C# client API codes will be generated. And if TypeScriptFolder is not defined, no TypeScript client API codes will be generated.

Hints: By default, WebApiClientAuto.ts is generated under "TypeScriptJQFolder" for jQuery, and WebApiNG2ClientAuto.ts is generated under "TypeScriptNG2Folder" for Angular 2. Sometimes you may want to customize the file names, then you may add property "TypeScriptJQFile": YourClientApi.ts or "TypeScriptNG2Folder": YourNG2ClientApi.ts into the JSON post.

NGVersion is a new setting introduced in WebApiClientGen 2.4. By default, WebApiClientGen 2.4 and greater will by default declare the import as import { Observable } from 'rxjs'; . If you are still using Angular 5.x, you need to declare "NGVersion" : 5 in the JSON config, so the import in the generated codes will be import { Observable } from 'rxjs/Observable'; .

For .NET client API

"ClientLibraryProjectFolderName" is the folder name of the client API library project, assumed to be the sibling project of the Web API project.

"ExcludedControllerNames" is a list of fully qualified controller names that are not exposed to the client API. There may be some API controllers are for Web browsers only, so you don't want them to be exposed to .NET client API.

"GenerateBothAsyncAndSync" indicates whether to generate both async functions and sync functions. By default, if not defined, the code gen will generate only async functions.

For TypeScript client API

"TypeScriptJQFolder" is an absolute path or relative path to the Web API project. By default, it should has value "Scripts\ClientApi" so the CodeGen will save the generated client API codes here in the root folder of your Web API project, while the NuGet package had already copied some scaffolding TypeScript codes: HttpClient.ts that the generated codes depend on. If you don't want to deliver client API codes in your Web API deployment, you may simply copy/move the ClientApi folder to elsewhere along with HttpClient.ts. And just make sure your Web API support cross site scripting if you prefer such separation.

"TypeScriptNG2Folder" is an absolute path or relative path to the Web API project. For example, "..\DemoAngular2\ClientApi" indicates an Angular 2 project created as a sibling project of the Web API project in the VS sln root; "c:\NG2Projects\MyFantasticSPA" points to your Angular 2 project.

If you don't want to generate client API codes for jQuery or Angular 2, you may simply not define TypeScriptJQFolder or TypeScriptNG2Folder.

The CodeGen generates strongly typed TypeScript interfaces from POCO classes according to "CherryPickingMethods" which is described in the doc comment below:

    /// <summary>
    /// Flagged options for cherry picking in various development processes.
    /// </summary>
    [Flags](Flags)
    public enum CherryPickingMethods
    {
        /// <summary>
        /// Include all public classes, properties and properties.
        /// </summary>
        All = 0,

        /// <summary>
        /// Include all public classes decorated by DataContractAttribute, and public properties or fields decorated by DataMemberAttribute. 
        /// And use DataMemberAttribute.IsRequired
        /// </summary>
        DataContract =1,

        /// <summary>
        /// Include all public classes decorated by JsonObjectAttribute, and public properties or fields decorated by JsonPropertyAttribute.  
        /// And use JsonPropertyAttribute.Required
        /// </summary>
        NewtonsoftJson = 2,

        /// <summary>
        /// Include all public classes decorated by SerializableAttribute, and all public properties or fields but excluding those decorated by NonSerializedAttribute.
        /// And use System.ComponentModel.DataAnnotations.RequiredAttribute.
        /// </summary>
        Serializable = 4,

        /// <summary>
        /// Include all public classes, properties and properties. 
        /// And use System.ComponentModel.DataAnnotations.RequiredAttribute.
        /// </summary>
        AspNet = 8,
    }

The default one is DataContract. And you may use any or combinations of methods.

Publish client API libraries

Build the client API project (Optional)

This step is not needed if you don't expect any client program coded on .NET Framework, or you would prefer to distribute the generated CS file.

Internal usages

The TypeScript file WebApiClientAuto.ts generated in ~Scripts/ClientApi is linked to your MVC/Web API project by default, thus it will be usable immediately in Visual Studio IDE at design time, and will be compiled into Javascript at compile time.

External usages

If you intend to let developers outside use the Web API, you may publish the client API source codes or the assembly in your Website every time you introduce breaking changes to the interfaces of the Web API.

Major Web services vendors like Google and Amazon typically publish both the API documents and the client API libraries for major programming languages.

References:

Remarks

Since Javascript supports only single dimensional array, this article "Tricky Array" may help you to deal with multidimensional array in Web API.

Hints

Help Pages and Strongly Typed Client API describes how to make doc comments of API controller available to the client API codes generated.

Crafting some batch files may automate the steps above at some degree. For more details, you may download the whole VS solution of this open source project and inspect those batch files included in VS projects. And it is recommended to make the client API library be strong named, if you decide to publish the assembly only, since some client programmers may have their client programs strong named.

And it shouldn't be hard to write scripts to automate some steps altogether for Continuous Integration.

Clone this wiki locally