Defining service interface types (MVC Web Service part 1)

I decided to start the process of creating a web service using an MVC like design pattern by specifying the interface towards the consumers. The interface has to be “nice”, and by that I mean that the parameters and return values should be easy to understand and use.

I will show how to define an XML schema using a third party tool, Liquid XML Studio 2008. These schemas will be used when generating C# classes/types to be used as parameters and return values when defining the web service interface. A result of this is that the web service will look like it uses objects as parameters, but this is only a way to represent the XML documents that may be used as parameters.

XSD (XML Schema Definition)

An XSD is an XML based alternative to DTD (Document Type Definition). The DTD is still more popular than the XSD, but personally I like the XSD more because of its stronger typing and the fact that an XSD is an XML document itself, which is not the case with a DTD.

For more information about XSD and DTD, consult Wikipedia (XSD, DTD) where you can find some nice examples as well as links to their specifications.
On http://en.wikipedia.org/wiki/XML_Schema_Language_Comparison there is a nice comparison between a number of XML schema types, listing pros and cons.

The web service interface

The goal with this article is to define a nice interface for the upcoming MVC like designed web service. The web service will expose two methods, according to the introduction. The parameters and return values are to be defined using an XML schema tool. The methods and their parameters are shown below:

// Returns a result XML document
public MVCWebserviceResultType SaveImages(MVCWebserviceImagesType images)

// Returns an XML document containing images (base64 coded)
public MVCWebserviceImagesType GetImages(string partOfFileName)

As seen above there are two types, MVCWebserviceResultType and MVCWebserviceImagesType, not yet defined, so let’s do it!

Specify the XML schemas

I will use Liquid XML Studio 2008 to specify the XML schemas. Look at the screenshot below showing the user interface when creating the MVCWebserviceResult schema:

The user interface is very good! The structure is built using the upper graphical part while the lower part lets you inspect and edit the schema the “rough” way. All changes are synchronized letting you edit the schema both using the graphical view and the textual view at the same time.

Liquid XML Studio is the best and easiest XML schema tool I’ve ever used!

The schemas are shown below:

MVCWebserviceResult.xsd

<?xml version="1.0" encoding="utf-8" ?>
<!--Created with Liquid XML Studio 6.1.18.0 - FREE Community Edition (http://www.liquid-technologies.com)-->
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="MVCWebserviceResult" type="MVCWebserviceResultType" />
<xs:complexType name="MVCWebserviceResultType">
<xs:sequence>
<xs:element minOccurs="1" maxOccurs="1" name="successful" type="xs:boolean" />
<xs:element minOccurs="1" maxOccurs="1" name="trace" type="ResultTrace" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ResultTrace">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="item">
<xs:complexType>
<xs:attribute name="name" type="xs:string" />
<xs:attribute name="length" type="xs:int" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:schema>

MVCWebserviceImages.xsd

<?xml version="1.0" encoding="utf-8" ?>
<!--Created with Liquid XML Studio 6.1.18.0 - FREE Community Edition (http://www.liquid-technologies.com)-->
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="MVCWebserviceImages" type="MVCWebserviceImagesType" />
<xs:complexType name="MVCWebserviceImagesType">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="1" name="images">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="image" type="ImageType" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element minOccurs="1" maxOccurs="1" name="supplier" type="SupplierType" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ImageType">
<xs:sequence>
<xs:element name="name" type="xs:string" />
<xs:element name="created" type="xs:dateTime" />
<xs:element name="data" type="xs:string" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="SupplierType">
<xs:sequence>
<xs:element minOccurs="1" maxOccurs="1" name="name" type="xs:string" />
<xs:element minOccurs="1" maxOccurs="1" name="country" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:schema>

Generate the classes

As a part of Microsoft Windows SDK comes a number of tools. The xsd tool is to be used when processing XML schemas. I will use this tool to generate the C# classes for the web service methods defined above.

The following commands will generate these types, executed from the Visual Studio Command Prompt:

xsd /classes /n:MVCArt.Models MVCWebserviceResult.xsd
xsd /classes /n:MVCArt.Models MVCWebserviceImages.xsd

Please note the /n option. This will place the generated classes in the namespace supplied, MVCArt.Models in this case. See screenshot below:

Below the generated class file for the MVCWebserivceResult.xsd is shown:

//------------------------------------------------------------------------------
// <auto-generated>
//     Denna kod har genererats av ett verktyg.
//     Körtidsversion:2.0.50727.3053
//
//     Ändringar i denna fil kan orsaka fel och kommer att förloras om
//     koden återgenereras.
// </auto-generated>
//------------------------------------------------------------------------------

//
// This source code was auto-generated by xsd, Version=2.0.50727.3038.
//
namespace MVCArt.Models {
    using System.Xml.Serialization;

    /// <remarks/>
    [System.CodeDom.Compiler.GeneratedCodeAttribute("xsd", "2.0.50727.3038")]
    [System.SerializableAttribute()]
    [System.Diagnostics.DebuggerStepThroughAttribute()]
    [System.ComponentModel.DesignerCategoryAttribute("code")]
    [System.Xml.Serialization.XmlRootAttribute("MVCWebserviceResult", Namespace="", IsNullable=false)]
    public partial class MVCWebserviceResultType {

        private bool successfulField;

        private ResultTraceItem[] traceField;

        /// <remarks/>
        public bool successful {
            get {
                return this.successfulField;
            }
            set {
                this.successfulField = value;
            }
        }

        /// <remarks/>
        [System.Xml.Serialization.XmlArrayItemAttribute("item", IsNullable=false)]
        public ResultTraceItem[] trace {
            get {
                return this.traceField;
            }
            set {
                this.traceField = value;
            }
        }
    }

    /// <remarks/>
    [System.CodeDom.Compiler.GeneratedCodeAttribute("xsd", "2.0.50727.3038")]
    [System.SerializableAttribute()]
    [System.Diagnostics.DebuggerStepThroughAttribute()]
    [System.ComponentModel.DesignerCategoryAttribute("code")]
    [System.Xml.Serialization.XmlTypeAttribute(AnonymousType=true)]
    public partial class ResultTraceItem {

        private string nameField;

        private int lengthField;

        private bool lengthFieldSpecified;

        /// <remarks/>
        [System.Xml.Serialization.XmlAttributeAttribute()]
        public string name {
            get {
                return this.nameField;
            }
            set {
                this.nameField = value;
            }
        }

        /// <remarks/>
        [System.Xml.Serialization.XmlAttributeAttribute()]
        public int length {
            get {
                return this.lengthField;
            }
            set {
                this.lengthField = value;
            }
        }

        /// <remarks/>
        [System.Xml.Serialization.XmlIgnoreAttribute()]
        public bool lengthSpecified {
            get {
                return this.lengthFieldSpecified;
            }
            set {
                this.lengthFieldSpecified = value;
            }
        }
    }
}

The xsd tool can generate classes for a number of languages:

  • C#
  • Visual Basic
  • Visual J#
  • JScript
  • C++

Read more about the xsd tool on MSDN
(XML Schema Definition Tool (Xsd.exe)).

Add the class files, together with the XSD files to the project. Visual Studio makes a good job grouping the files together which makes to solution explorer look like below. One really good thing with Liquid XML Studio is that it integrates with the IDE and modification of the schemas may be done using all Liquid XML Studio features from within Visual Studio.

The solution explorer above is a result from the upcoming article about setting up the Visual Studio Solution to make way for a successful implementation of the MVC like design.

Now be amazed by the ease of use with intellisense:

Result

Using an XML schema tool or create the schema “by hand” and then generate class files using the xsd tool will make life much easier when defining a service interface. There are a bunch of class generating tools for different languages, so the developers on the consumer side will not be angry even if the service exposes methods with object parameters. Underneath that there are XML documents…

Look at the resulting class below:

Next up

In the next article in the series I will show how I have setup the Visual Studio Solution, to make way for the implementation of business logic in the article after that.

Links

  • Part 2:
Tagged with: , , , , ,
Posted in .NET, ASP.NET, C#, XML
4 comments on “Defining service interface types (MVC Web Service part 1)
  1. My friend mentioned to me your site, so I thought I’d check it out. Very interesting material, will be back for more!

  2. Linnea Kuzma says:

    Someone I work with visits your site frequently and recommended it to me to read as well. The writing style is great and the content is interesting. Thanks for the insight you provide the readers!

  3. Hyo Pomarico says:

    Hello can I use some of the insight found in this site if I link back to you?

  4. You’ve got great insights about Web Services, keep up the good work!

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>