Web Services and C# Enums

Web Service Transparency

.NET support for web services is excellent in creating illusion of transparency. General process is quite straightforward:

On the server we create a web service, decorating publicly visible methods with [WebMethod] attribute.
On the client we add a web reference to the service, and proxy code is automatically generated for us by VIsual Studio. We can then call web service methods almost as if they were local methods.

All arguments and return values get magically XML-serialized, transmitted to the peer, and de-serialized to something very close to the original form. Ideally, this whole process should be automatic and seamless.

Imperfect Transparency of Enums

It turns out that enums are not as transparent as we'd like them to be. There are three sticky issues:

If server-side code declares an enum and assigns specific numeric values to its members, these values will not be visible to the client.
If server-side code declares a [Flags] enum with "compound" mask values (as in White = Red|Green|Blue), it is not properly reflected on the client side.
If server or client transmits an "illegal" value which is outside of the scope of the enum, it causes an exception in XML de-serializer on the other side.

Numeric Values Are Not Preserved

If we have server-side definition like this:

enum StatusCode
{
    Success = 200,
    NotFound = 404,
    Denied  = 401
}

it is translated to client-side definition like this:

enum StatusCode
{
    Success = 1,
    NotFound = 2
    Denied  = 3
}

Corresponding WSDL looks as follows:

<s:simpleType name="StatusCode">
    <s:restriction base="s:string">
        <s:enumeration value="Success"/>
        <s:enumeration value="NotFound"/>
        <s:enumeration value="Denied"/>
    </s:restriction>
</s:simpleType>

As one can see, there is no mension of numeric values in the WSDL. Proxy code generator on the client side does not have access to anything but WSDL. Therefore, it does not have a chance to get numeric values of enum members.

An important side effect of this phenomenon is that the relative order of enum members may not be preserved. For instance, in the example above, expression (StatusCode.NotFound > StatusCode.Denied)
is true on the server, and false on the client.

Relationships Between [Flags] Masks May Be Broken

Server-side declaration:

[Flags]
enum UserRights
{
	Read = 16,
	Write = 256,
	Delete = 1024,
	AllAccess = Read | Write | Delete
}

Client-side declaration (some insignificant decorations removed):

[Flags]
enum UserRights
{
   Read = 1,
   Write = 2,
   Delete = 4,
   AllAccess = 8
}

Corresponding WSDL:

<s:simpleType name="UserRights">
    <s:restriction base="s:string">
        <s:enumeration value="Read"/>
        <s:enumeration value="Write"/>
        <s:enumeration value="Delete"/>
        <s:enumeration value="AllAccess"/>
    </s:restriction>
</s:simpleType>

Therefore, on the client UserRights.AllAccess lost its relationship to other user right values. On the server expression
(UserRights.AllAccess & UserRights.Read) != 0
is true, while on the client it is false.

This can lead to disastrous consequences.

Out-Of-Range Values Cause Exception on Receiving End

The following server-side code:

enum Test
{
    SomeValue = 1
}

[WebMethod]
public Test GetValue()
{
   return (Test)512;
}

will cause "invalid XML document" exception on the client side when reading GetValue() response. This exception is related to how XML serializer works with enums. "Legal" values are transmitted as text. E.g. value of 1 would be transmitted as <Test>SomeValue</Test>. For [Flags] enums multiple text strings are transmitted to indicate concatenation of several masks, e.g. <UserRights>Read Write</UserRights>. However, out-of-range values are transmitted as stringified integers, e.g. <Test>512</Test>. These integers are not understood at the receiving end and cause exception.

Controlling Generated XML

It seems that .NET framework does not give you much leeway in controlling XML generated for enums. In particular, constructs like :

[XmlElement(typeof(int))]
enum MyEnum
{
    ...
}

[XmlElement(DataType="integer")]
enum MyEnum
{
    ...
}

do compile, but fail miserably at run-time.

One useful attribute is [XmlEnum], which allows to change names of enum members. As we mentioned before, enum members are transmitted as literal strings. Therefore, if one has flags enum like this:

[Flags]
enum MyMask
{
    VeryVeryLongFlagNameWillBeTransmittedToClient,
    AnotherQuiteLongFlagNameAlongTheFirstOne,
    EtCeteraEtCetera
}

generated XML can get quite verbose. To prevent this, transmitted literal strings may be changed using [XmlEnum]:

[Flags]
enum MyMask
{
    [XmlEnum("VeryLong")] VeryVeryLongFlagNameWillBeTransmittedToClient,
    [XmlEnum("Another")]  AnotherQuiteLongFlagNameAlongTheFirstOne,
    [XmlEnum("EtCetera")] EtCeteraEtCetera
}

Conclusion

Extra caution must be excercised when transmitting enums over web service boundary. Behavior of XML serializer is not always straightforward for enums, and sometimes can cause serious incompatibilities between client and server. To ensure correct operation of software, one must keep in mind its limitations. If numeric values need to be preserved across the wire, they must be transferred as integers, not enums. In this case, however, client must have ad-hoc knowledge regarding what value means what.

.NET framework provides limited means of manipulating XML generated for enums. In particular, we were unable to find an attribute that would allow to automatically transmit enum as int.

Feedback

Questions? Comments? Feel free to
Leave feedback

Programming Tools & Info