XML-RPC.NET

Cook Computing

Latest News

22nd May 2005

Version 0.9.2 has been released.

Current Release - 0.9.2

xml-rpc.net.0.9.2.zip

Changes

Overview

XML-RPC.NET is a library for implementing XML-RPC Services and clients in the .NET environment.The library has been in development since March 2001 and is used in many open-source and business applications. The current version of XML-RPC.NET is 0.9.1. Its features include:

- interface based definition of XML-RPC servers and clients
- code generation of type-safe client proxies
- support for .NET Remoting on both client and server
- ASP.NET Web Services which support both XML-RPC and SOAP
- client support for asynchronous calls
- client support for various XML encodings and XML indentation styles
  (some other XML-RPC server implementations incorrectly only accept certain indentation styles)
- built-in support for XML-RPC Introspection API on server
- dynamic generation of documentation page at URL of XML-RPC end-point
- support for mapping XML-RPC method and struct member names to .NET-compatible names
- support for Unicode XML-RPC strings in both client and server
- support for optional struct members when mapping between .NET and XML-RPC types

The XML-RPC.NET library is CLS-compliant and so can be called from any CLS-compliant language, the main examples being C# and VB.NET.

The FAQ provides more information and the mailing list - the XMLRPCNET Yahoo group - contains discussion, peer support, code example, and announcements relating to XML-RPC.NET.

A couple of sample XML-RPC services implemented using XML-RPC.NET are available:

XML-RPC Clients

It is easy to create client code which makes calls to XML-RPC servers. All you need to do is define an interface representing the XML-RPC end-point and then use the XmlRpcProxyGen class to automatically generate the code for the proxy.

[XmlRpcUrl("http://betty.userland.com/RPC2")]
interface IStateName
{
    [XmlRpcMethod("examples.getStateName")]
    string GetStateName(int stateNumber); 
}

The proxy instance is generated using static method Create of the XmlRpcProxyGen class:

IStateName proxy = (IStateName)XmlRpcProxyGen.Create(typeof(IStateName));

The method on the proxy can then be called to make the XML-RPC request to the server:

string stateName = proxy.GetStateName(41);

XML-RPC Services

XML-RPC.NET implements XML-RPC services as Services running in the Microsoft IIS web server environment. The model for XML-RPC Services are SOAP-based Web Services implemented as part of ASP.Net. An XML-RPC Service is implemented (in any CLS-compliant language, e.g. C#, VB.Net, etc) by creating a class which derives from the XmlRpcService base class and decorating the methods to be exposed via XML-RPC with the XmlRpcMethod attribute. For example:

public class StateNameService : XmlRpcService 
{
  [XmlRpcMethod("examples.getStateName",
    Description="Return name of state given its number")] 
  public string getStateName(int stateNum)
  {
    if (stateNum == 41)
      return "South Dakota";
    else
      return "Don't know";
  }
}

As well as specifying an XML-RPC method the XmlRpcMethod attribute is here used to specify that the method is to be called using the XML-RPC protocol as "examples.getStateName", not the name of the method used in the Service class.The string assigned to Description is used for automatic documentation generation as described below when a Service is invoked via a HTTP GET request.

Alternatively the service class may also derive from an interface which defines the XML-RPC methods. The interface can then be also used to generate a proxy class as described above. For example, using the IStateName interface defined earlier:

public class StateNameService : XmlRpcService, IStateName
{
  public string getStateName(int stateNum)
  {
    if (stateNum == 41)
        return "South Dakota";
    else
      return "Don't know";
  }
}

A class may implement many XML-RPC methods, not just a single method as in these examples.

The resulting assembly DLL placed in the bin directory of an IIS virtual directory and a web.config file is used to dispatch HTTP requests to the custom handler implemented by class XmlRpcService. For example, if cookcomputing.com has a virtual directory called xmlrpc and the following config file is placed in the root directory of xmlrpc:

<configuration>
  <system.web>
    <httpHandlers>
      <add verb="*" path="statename.rem" 
        type="CookComputing.StateNameService, StateNameService" />
    </httpHandlers>
  </system.web> 
</configuration>

The Service can be invoked via the XML-RPC protocol at this URL:

    http://localhost/xmlrpc/statename.rem

Note that the type is assembly qualified: the name of the class is CookComputing.StateNameService in the assembly StateNameService (i.e. StateNameService.dll).

If, instead of making an XML-RPC request via a HTTP POST request, the caller makes a HTTP GET request to the same URL, the Service returns an automatically generated page describing itself. For the example service above, this page is returned.

Alternatively the Service can implemented via XML-RPC.NET's support for .NET Remoting.This has the advantage that the same Service can then be accessed by either the XML-RPC or SOAP protocols.

Further Information

FAQ - this provides the documentation for XML-RPC.NET.

Samples - several samples are available.

Status - bugs in current release and todo list.

Release History

Release history is available here.

Developers

Lead Developer - Charles Cook.

License

XML-RPC.NET is released under the terms of the MIT X11 license.

Contact

Please contact with any feedback or suggestions for XML-RPC.NET.

 

© Charles Cook, 2001-2005 All Rights Reserved.
22 May 2005