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 { ... }
or
[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.
转载地址:http://www.ikriv.com/dev/dotnet/WebServices_and_Enums.html
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 现代计算机视觉入门之:什么是图片特征编码
· .NET 9 new features-C#13新的锁类型和语义
· Linux系统下SQL Server数据库镜像配置全流程详解
· 现代计算机视觉入门之:什么是视频
· 你所不知道的 C/C++ 宏知识
· 不到万不得已,千万不要去外包
· C# WebAPI 插件热插拔(持续更新中)
· 会议真的有必要吗?我们产品开发9年了,但从来没开过会
· 【译】我们最喜欢的2024年的 Visual Studio 新功能
· 如何打造一个高并发系统?