WCF服务编程设计规范(4):操作与错误设计

WCF服务编程设计规范(4):操作与错误设计。主要包含服务操作与调用、错误设计规范。中英对照。欢迎留言交流。下一节会介绍事务、并发管理和队列服务的内容。

Operations and Calls

操作与调用

1. Do not treat one-way calls as asynchronous calls.

         不要把单向调用作为异步调用

2. Do not treat one-way calls as concurrent calls.

         不要把单向调用作为并发调用

3. Expect exceptions from a one-way operation.

         单向操作也应该返回异常

4. Enable reliability even on one-way calls. Use of ordered delivery is optional for one way calls.

         即使当单向调用的时候，也要启用可靠性。单向调用不必使用有序传递。

5. Avoid one-way operations on a sessionful service. If used, make it the terminating operation:

         避免在会话服务里使用单向调用。如果用到，作为结束操作。

[ServiceContract(SessionMode = SessionMode. Required)]

interface IMyContract

{

[OperationContract]

void MyMethod1();

[OperationContract( IsOneWay = true ,IsInitiating = false, IsTerminating = true )]

void MyMethod2();

}

6. Name the callback contract on the service side after the service contract name, suffixed by Callback :

         回调操作最好使用服务契约的名字加后缀 Callback

interface IMyContractCallback

{...}

[ServiceContract(CallbackContract = typeof( IMyContractCallback))]

interface IMyContract

{...}

7. Strive to mark callback operations as one-way.

         回调操作标记会单向操作

8. Use callback contracts for callbacks only.

         只在回调的时候使用回调契约。

9. Avoid mixing regular callbacks and events on the same callback contract.

         避免在回调契约上混用常规回调和事件

10. Event operations should be well designed:

         事件操作应该设计如下：

a) void return type

    避免返回类型

b) No out-parameters

         没有 out 参数

c) Marked as one-way operations

         标记为单向操作

11. Avoid using raw callback contracts for event management, and prefer using the publish-subscribe framework.

         避免在事件管理中使用原始回调契约，推荐使用发布 - 订阅框架

12. Always provide explicit methods for callback setup and teardown:

         为回调提供清晰的安装 (setup) 和拆卸 ( teardown) 方法

[ServiceContract(CallbackContract = typeof(IMyContractCallback))]

interface IMyContract

{

[OperationContract]

void DoSomething();

[OperationContract]

void Connect();

[OperationContract]

void Disconnect();

}

interface IMyContractCallback

{...}

13. Use the type-safe DuplexClientBase<T,C> instead of

DuplexClientBase<T> .

         使用类型安全的 DuplexClientBase<T,C> 代替 DuplexClientBase<T> .

 

14. Use the type-safe DuplexChannelFactory<T,C> instead of

DuplexChannelFactory<T> .

         使用类型安全的 DuplexChannelFactory<T,C> 代替 DuplexChannelFactory<T> .

 

15. When debugging or in intranet deployment of callbacks over the WSDualHttpBinding , use the CallbackBaseAddressBehavior attribute with CallbackPort set to 0 :

         当调试或在企业局域网部署环境里使用 WSDualHttpBinding 时，使用 CallbackBaseAddressBehavior ，并把 CallbackPort 设置 0 ：

[CallbackBaseAddressBehavior( CallbackPort = 0 )]

class MyClient : IMyContractCallback

{...}

Faults

错误

1. Never use a proxy instance after an exception, even if you catch that exception.

         不要异常以后使用代理实例，尽管你捕获了异常。

2. Avoid fault contracts and allow WCF to mask the error.

         避免错误契约，让 WCF 来包装错误

3. Do not reuse the callback channel after an exception even if you catch that exception, as the channel may be faulted.

         不要在异常后还使用回调通道，尽管你捕获了异常，因为通道可能出于错误状态。

4. Use the FaultContract attribute with exception classes, as opposed to mere serializable types:

在异常类上使用 FaultContract 属性，而不是可序列化类型上：

//Avoid: 避免

[OperationContract]

[FaultContract(typeof( double))]

double Divide(double number1,double number2);

//Correct: 正确

[OperationContract]

[FaultContract(typeof( DivideByZeroException))]

double Divide(double number1,double number2);

5. Avoid lengthy processing such as logging in IErrorHandler.ProvideFault() .

         避免冗长的处理，比如登入 IErrorHandler.ProvideFault() .

 

6. With both service classes and callback classes, set IncludeExceptionDetailInFaults to true in debug sessions, either in the config file or programmatically:

         对于服务类和回调类，在调试时，设置 IncludeExceptionDetailInFaults 为 true ，配置文件或者编程都可以：

public class DebugHelper

{

public const bool IncludeExceptionDetailInFaults =

#if DEBUG

true;

#else

false;

#endif

}

[ServiceBehavior(IncludeExceptionDetailInFaults =

DebugHelper.IncludeExceptionDetailInFaults)]

class MyService : IMyContract

{...}

7. In release builds, do not return unknown exceptions as faults except in diagnostic scenarios.

         在发布构建版本里，不要返回不可知的异常做为错误，除非是在调试场景里。

8. Consider using the ErrorHandlerBehavior attribute on the service, both for promoting exceptions to fault contracts and for automatic error logging:

         当提升异常为错误契约，以及自动错误日志时，都可以考虑在服务上使用 ErrorHandlerBehavior 属性：

[ErrorHandlerBehavior]

class MyService : IMyContract

{...}

9. Consider using the CallbackErrorHandlerBehaviorAttribute on the callback client, both for promoting exceptions to fault contracts and for automatic

error logging:

     当提升异常为错误契约，以及自动错误日志时，考虑在回调客户端上使用 CallbackErrorHandlerBehaviorAttribute ：

[CallbackErrorHandlerBehavior(typeof(MyClient))]

class MyClient : IMyContractCallback

{

public void OnCallabck()

{...}

}

前面相关文章：

1. WCF服务编程设计规范(1)：最新版WCF Coding Standard 介绍和下载

2. WCF服务编程设计规范(2):序言、通用设计规范和要点

3. WCF服务编程设计规范(3):服务契约、数据契约和实例管理设计规范