Documentation   Cook Computing



XML-RPC.NET

Latest News

19th December 2008

Version 2.4.0 has been released: xml-rpc.net.2.4.0.zip

New feature and fixed issues:

Note: if you use the built-in compressed folders feature of Windows Explorer in Windows XP to extract file from the distribution, you may find that the contents of the bin directories are not visible. Use a utility such as WinZip instead.

Overview

XML-RPC.NET is a library for implementing XML-RPC Services and clients in the .NET environment, supporting versions 1.0, 1.1, and 2.0 of the .NET runtime. The library has been in development since March 2001 and is used in many open-source and business applications. Its features include:

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")]
public interface IStateName : IXmlRpcProxy
{
    [XmlRpcMethod("examples.getStateName")]
    string GetStateName(int stateNumber); 
}

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

IStateName proxy = XmlRpcProxyGen.Create<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: 

public interface IStateName
{
    [XmlRpcMethod("examples.getStateName")]
    string GetStateName(int stateNumber); 
}

public interface IStateNameProxy : IStateName, IXmlRpcProxy
{
}

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.

Google Code Project

As of version 2.2.0, XML-RPC.NET is hosted at Google Code:

Samples - several samples are available - see distribution.

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 (more).

Contact

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

 

Charles Cook, 2001-2009 All Rights Reserved. 10th April 2009