This topic contains the following sections.

The CSO Gateway

CSO Gateway stands for Client Side Object Gateway. It is an object-oriented bridge between the ASP.NET worker process and the javascript runtime. It allows ASP.NET developers to seamlessly bring object oriented data on the client side while preserving the underlying class hierarchy and the object composition graph.

Object-oriented paradigm

The major obstacle to what the CSO Gateway is trying to acheive is that the server-side languages (C#, VB.NET, C++) are object-oriented languages while the client-side language is a scripting language. Javascript supports prototype-based programming through the prototype and constructor properties and the new operator and when those features are used properly, they implement most of the object oriented paradigm. Part of the gap is filled by using the Microsoft Ajax client-side library. The Type class is particularly useful. It provides methods to abstract most of the prototype/constructor hookups neccessary to acheive inheritance. It also provides support for namespaces, and a range of relection-like methods.

The prototype-based programming aspect of javascript plus the Microsoft Ajax client-side library is the CSO Gateway's implementation of the object-oriented paradigm.

Classes, Interfaces, Enums

The CSO Gateway supports not only client-side classes but also interfaces and enums. The Microsoft Ajax client-side library provides 3 methods to register new client-side types: registerClass, registerInterface and registerEnums. Once a type is registered, it can take full advantage of the Type class and other extensions provided by the Microsoft AJAX library.

Inheritance, Interface implementation, composition

Client side classes can have a base class, derived classes and implement interfaces. Instances can be composed of instances of other classes, not just primitive types.

Automatic javascript type creation

Usually, almost no action from the developer is necessary to create a client-side type as the CSO Gateway is creating them at runtime by introspection of the equivalent type on the server-side. Some control on how the type is generated is given to the developper through code attributes.

Automatic transformation of objects into "javascript objects"

There isn't much to do to transform the server-side object into a client-side object either: simple assign the object to the ObjectGateway control and a script tag containing javascript code that instantiate an equivalent client-side object will be rendered on the page.

Automatic creation and ordering of script tags for external scripts

Library of javascript types

Easy to use

The CSO Gateway is powerfull but very easy to use. You install the CSO Gateway in your web project by creating a reference to a dll and simple entity objects are brought on the client side by decorating a class with an attribute and assign the object to a web control.

Customizable and Extensible


This section describes features that will be available in future releases

The CSO Gateway has an
extensible architecture that exposes many hooks to override and customize its behavior. If the web developper doesn't like how the CSO Gateway is converting one of the primitive type or one of its user-defined type, it is easy to create a class that implements the IToClientSideConverter interface and take the matter into his own hands.

About this document

The CSO Gateway is in its BETA phase and the documentation is not complete. Perharps the most important piece missing is the reference (the exact behavior of the CSO Gateway). On the other hand, the API is pretty complete, both client-side and server-side, and what is in the Getting started section is more than enough to get you started with the CSO Gateway.

To make the discussion consice, this document uses a number of custom terms like cso-native type and cso-compatible type. Refer to the Glossary for their definition.

In its current state, this document is strongly C#-biased. It is a goal though not a priority to make it equal for C#/VB.NET/C++.


The first line of codes of what is now the CSO Gateway were written in March of 2007. At that time, people at my workplace were using JSON without the help of a serializer. Huge, complex and buggy for loops nested 10 deep were used to generated chaotic JSON strings and I hated it. Around the same time I was reading an AJAX book and I became aware of the object-oriented extension of the Microsoft AJAX library.

Few days later I had the first version of what is now the Object Gateway component: a web control that takes an object and renders a constructor call that creates an equivalent object in javacript. But at that point, the javascript classes were still coded manually which was somewhat time-consuming and even though we started to use my little thing in production, I knew that it was not much better than JSON if you gonna have to write one or more javascript classes each time you wanna bring a new type of objects on the client. With little spare time on my hands, the project went to sleep for almost a year.

Then in June of 2008 a new engineer joined my team. He had some time to kill and I decided to put him on coding a javascript class generator and a HTTP handler to serve them. The thing went to production quickly and the full potential of the CSO Gateway was now obvious. I started to put in some spare time here and there, always towards the seamless transportation of objects from the server to the client. In May of 2009 the CSO Gateway became an open source project.


If you use the CSO Gateway, you can contriubte by:

The CSO Gateway is an open source project developed on my personal time. If you use the CSO Gateway, find it usefull and would like to see it improve, you can support future development by making a donation. Paypal is an easy, fast and secure way to donate.

Make donations with PayPal - It's fast, free and secure!