Saturday, February 25, 2012

Wcf and Node.js, better together

@YaronNaveh

(get wcf.js on github!)

Take a look at the following code:


Do you see anything...um, special? Well c# already has the "var" keyword since version 3.0 so maybe it is some kind of a c#-ish dialect? Or maybe it is a CTP for javascript as a CLR language? Or something related to the azure sdk for node.js?

Not at all. This is a snippet from wcf.js - a pure javascript node.js module that makes wcf and node.js work together!

As node assumes its central place in modern web development, many developers build node apps that must consume downstream wcf services. Now if these services use WCF Web API ASP.NET Web API it is very easy. It is also a breeze if you are in a position to add a basic http binding to the Wcf service, and just a little bit of more work if you plan to employ a wcf router to do the protocol bridging. Wcf.js is a library that aims to provide a pure-javascript development experiece for such scenarios.

Note that building new node.js ws-* based services is a non-goal for this project. Putting aside all the religious wars, Soap is not the "node way", so you should stick to Rest where you'll get good language support (json) and built-in libraries.

"Hello, Wcf... from node"

You are closer than you think to consume your first Wcf service node.js:

1. Create a new wcf web site in VS and call it "Wcf2Node". If you use .Net 4 than BasicHttpBinding is the default, otherwise in web.config replace WsHttp with BasicHttp. No need to deploy, just run the service in VS using F5.

2. Create anywhere a folder for the node side and from the command line enter its root and execute:

$> npm install wcf.js

3. In the same folder create test.js:

var BasicHttpBinding = require('wcf.js').BasicHttpBinding
  , Proxy = require('wcf.js').Proxy
  , binding = new BasicHttpBinding()
  , proxy = new Proxy(binding, " http://localhost:12/Wcf2Node/Service.svc")
  , message = '<Envelope xmlns=' +
            '"http://schemas.xmlsoap.org/soap/envelope/">' +

                 '<Header />' +
                   '<Body>' +
                     '<GetData xmlns="http://tempuri.org/">' +
                       '<value>123</value>' +
                     '</GetData>' +
                    '</Body>' +
               '</Envelope>'

proxy.send(message, "http://tempuri.org/IService/GetData", function(response, ctx) {
  console.log(response)
});


4. In test.js, change the port 12 (don't ask...) to the port your service runs on.

5. Now we can execute node:

$> node test.js

6. You should now see the output soap on the console.

Of course this sample is not very interesting and you may be better off sending the raw soap using request. Let's see something more interesting. If your service uses ssl + username token (transport with message credential), the config may look like this:

<wsHttpBinding>
    <binding name="NewBinding0">
        <security mode="TransportWithMessageCredential">
            <message clientCredentialType="UserName" />
        </security>
    </binding>
</wsHttpBinding>

The following modifications to the previous example will allow to consume it from node:

...
binding = new WSHttpBinding(
        { SecurityMode: "TransportWithMessageCredential"
        , MessageClientCredentialType: "UserName"
        })
...

proxy.ClientCredentials.Username.Username = "yaron";
proxy.ClientCredentials.Username.Password = "1234";
proxy.send(...)

And here is the wire soap:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">

<Header>
  <o:Security>
    <u:Timestamp>
      <u:Created>2012-02-26T11:03:40Z</u:Created>
      <u:Expires>2012-02-26T11:08:40Z</u:Expires>
    </u:Timestamp>
    <o:UsernameToken>
      <o:Username>yaron</o:Username>
      <o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">1234</o:Password>
    </o:UsernameToken>
  </o:Security>
</Header>

<Body>
  <EchoString xmlns="http://tempuri.org/">
    <s>123</s>
  </EchoString>
</Body>


If you use Mtom check out this code:

(The formatting here is a bit strage due to my blog layout - it looks much better in github!)

var CustomBinding = require('wcf.js').CustomBinding

  , MtomMessageEncodingBindingElement = require('wcf.js').MtomMessageEncodingBindingElement

  , HttpTransportBindingElement = require('wcf.js').HttpTransportBindingElement

  , Proxy = require('wcf.js').Proxy
  , fs = require('fs')
  , binding = new CustomBinding(
        [ new MtomMessageEncodingBindingElement({MessageVersion: "Soap12WSAddressing10"}),
        , new HttpTransportBindingElement()
        ])

  , proxy = new Proxy(binding, "http://localhost:7171/Service/mtom")
  , message = '<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope">' +
                '<s:Header />' +
                  '<s:Body>' +
                    '<EchoFiles xmlns="http://tempuri.org/">' +
                      '<value xmlns:a="http://schemas.datacontract.org/2004/07/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">' +
                        '<a:File1 />' +                   
                      '</value>' +
                    '</EchoFiles>' +
                  '</s:Body>' +
              '</s:Envelope>'

proxy.addAttachment("//*[local-name(.)='File1']", "me.jpg");

proxy.send(message, "http://tempuri.org/IService/EchoFiles", function(response, ctx) {
  var file = proxy.getAttachment("//*[local-name(.)='File1']")
  fs.writeFileSync("result.jpg", file)    
});

Mtom is a little bit trickier since wcf.js needs to know which nodes are binary. Using simple xpath can help you achieve that.

Getting your hands dirty with Soap
Wcf.js uses soap in its raw format. Code generation of proxies does not resonate well with a dynamic language like javascript. I also assume you are consuming an existing service which already has working clients so you should be able to get a working soap sample. And if you do like some level of abstraction between you and your soap I recommend node-soap, though it still does not integrate with wcf.js.

If you will use raw soap requests and responses you would need a good xml library. And while node has plenty of dom / xpath libraries, they are not windows friendly. My next post will be on a good match here.

Supported standards
Wcf implements many of the ws-* standards and even more via proprietary extensions. The first version of wcf.js supports the following:

  • MTOM

  • WS-Security (Username token only)

  • WS-Addressing (all versions)

  • HTTP(S)

    The supported binding are:


  • BasicHttpBinding

  • WSHttpBinding

  • CustomBinding

    What do you want to see next? Let me know.

    Get the code
    Wcf.js is hosted in GitHub, and everyone is welcome to contribute features and fixes if needed.
    Wcf.js is powered by ws.js, the actual standards implementation, which I will introduce in an upcoming post.
  • @YaronNaveh

    What's next? get this blog rss updates or register for mail updates!