Module: DotNetServices

Defined in:
lib/dot_net_services.rb,
lib/dot_net_services/error.rb,
lib/dot_net_services/session.rb,
lib/dot_net_services/authentication.rb,
lib/dot_net_services/message_buffer.rb

Overview

DotNetServices is the top-level namespace of .NET Services for Ruby, Ruby interoperability layer for .NET Services plain HTTP (REST) API.

.NET Services

Since you are reading this, you probably already know that .NET Services is a Microsoft product, described as the “Internet Services Bus”, a messaging bus in the cloud. Like any other messaging bus, it helps services and consumers to communicate with each other. Further information on .NET Services can be found on MSDN: go.microsoft.com/fwlink/?LinkID=129428.

While .NET Services primarily target .NET platform, non-Microsoft software is also catered for, by providing open protocols for most of the bus functionality, in both SOAP/WS-* and plain HTTP style. The latter is structured in a way that makes it easy to implement REST interactions over the bus, including both synchronous and asynchronous semantics. .NET Services bus doesn’t force an application to use REST, any other kind of plain HTTP protocol can be routed through it, too.

Functionality

This library is a simple Ruby wrapper for .NET Services plain HTPP (REST) APIs. Current version allows Ruby developers to build consumers of synchronous RESTful services (implemented as .NET WCF services, using webHttpRelayBinding, provided by the .NET Services SDK). You can also exchange messages between Ruby processes via Volatile Message Buffers (VMBs), which are .NET Services mechanism for asynchronous communications.

.NET Services for Ruby looks like Net::HTTP API from the standard library, but deals with authentication, VMB management and message retrieval.

Since this is a 0.1.0 version of an interoperability layer for a PDC version of a bus, a few things are missing.

Most notably, with this version you still can not:

  • communicate with WCF services bound by anything other than webHttpRelayBinding.

  • communicate with the bus via WS-* protocols.

  • communicate with a WCF-based service via a VMB. At least, not until .NET Services SDK adds a WCF binding for

REST via VMB. Once it’s available, we should be able to work with it.

  • use VMB pub-sub and multicast functionality

  • use Workflow Services

  • use Identity Service as a dfederated identity provider for end-users

Usage examples

Say, you are a cellphone dealer. You have a Point of Sale web application, written in Rails. It sells cellphones. The phones you sell are operated by a phone company, which offers a .NET Services solution (group of services in the .NET Services world), called Dealership. It includes two services, Customer and Provisioning.

Customer service is a RESTful service endpoint, implemented by WCF service with a webHttpRelayBinding. It’s listening on /Customer URL, and provides the usual CRUD functionality for managing customers.

Provisioning service endpoint is a VMB. Coincidentally, it’s also written in Ruby! :) When a customer buys a new phone, provisioning application should activate the phohe on the network, so that the customer can actually make calls with it. Activation can take several minutes, even hours, and we don’t want the point of sale terminal to hang until it’s over. Hence the use of a VMB as an asynchronous communication device.

To create a customer, point of sale app needs to post a URL-encoded form to a webHttpRelayBinding endpoint. That’s where you need to use a DotNetServices::Session class:

require 'dotnetservices'
session = DotNetServices::Session.open("/Dealership/Customer", :username => 'Dealership', :password => '_password')
session.post :first_name => 'John', :last_name => 'Doe'

Posting a message to a Provisioning endpoint would actually look the same:

session = DotNetServices::Session.open("/Dealership/Provisioning", :username => 'Dealership', :password => '_password')
session.post :phone_number => '555 888-8888'

DotNetServices::MessageBuffer is needed by the Provisioning service (and not the client), to register the VMB and retrieve messages from it. Usage typically looks like this:

buffer = DotNetServices::MessageBuffer.new("/Dealership/Provisioning",
                                           :username => 'Dealership', :password => '_password')
buffer.open_and_poll do |message|
  ... process incoming messages ...
end

This code will check that the VMB exists, create one if necessary, and continuously poll it for new messages. Whenever a new message is sent to VMB, MessageBuffer#open_and_poll retrieves it and invokesthe block, passing it a Net::HTTP::Request instance that looks exactly like what the sender originally sent to the VMB. Nice and easy.

To understand and use .NET Services for Ruby, you should probably also read the documentation for the two classes mentioned above: DotNetServices::Session and DotNetServices::MessageBuffer.

Happy bussing!

Defined Under Namespace

Modules: Authentication Classes: AuthenticationError, MessageBuffer, Session

Class Method Summary collapse

Class Method Details

.host_port ⇒ Object

Host and port of the bus endpoint.



112
113
114
115
116
117
 
# File 'lib/dot_net_services.rb', line 112

def host_port
  return @host_port if @host_port
  uri = URI.parse(root_url) 
  @host_port = [uri.host, uri.port]
  @host_port
end

.identity_host ⇒ Object

The name of the host providing DotNetServices identity services.



100
101
102
 
# File 'lib/dot_net_services.rb', line 100

def identity_host
  'accesscontrol.windows.net'
end

.logger ⇒ Object

TODO implement!



136
137
138
139
140
141
142
 
# File 'lib/dot_net_services.rb', line 136

def logger
  if RAILS_ENV
    nil
  else
    @logger ||= nil
  end
end

.proxy ⇒ Object

An HTTP proxy to connect through.

Defaults to Net::HTTP (direct connection without proxy). To set a proxy, see #use_proxy.



131
132
133
 
# File 'lib/dot_net_services.rb', line 131

def proxy
  @proxy || Net::HTTP
end

.relay_host ⇒ Object

The name of the host providing DotNetServices relay services.



95
96
97
 
# File 'lib/dot_net_services.rb', line 95

def relay_host
  "servicebus.windows.net"
end

.root_url ⇒ Object

The root URL used for exposing services.



105
106
107
108
109
 
# File 'lib/dot_net_services.rb', line 105

def root_url
  # Modified as per changes in enpoint URL naming conventions in

  # .Net Services March 09 CTP release (M5)

  "#{relay_host}/"
end

.use_proxy(proxy_host, proxy_port, proxy_user = nil, proxy_password = nil) ⇒ Object

Use an HTTP proxy to connect to .NET Services

If you call this method, all subsequent communications with .NET Services will use an HTTP proxy. You must given hostname and password #use proxy

DotNetServices.use_proxy()



124
125
126
 
# File 'lib/dot_net_services.rb', line 124

def use_proxy(proxy_host, proxy_port, proxy_user = nil, proxy_password = nil)
  @proxy = Net::HTTP::Proxy(proxy_host, proxy_port, proxy_user, proxy_password)
end