第四章 创建 Web Services

介绍如何创建web服务的基础知识。

Web Services概述

创建 Web 服务，需要创建一个扩展 %SOAP.WebService 的类，该类提供通过 SOAP 协议调用一个或多个方法所需的所有功能。此外，此类还自动管理与 SOAP 相关的协议，例如维护描述服务的 WSDL 文档。

基本要求

创建 Web 服务，请创建并编译满足以下基本要求类：

• 该类必须扩展 %SOAP.WebService。
• 该类必须定义 SERVICENAME 参数。不会编译该类，除非它定义了此参数。
• 此类应定义用 WebMethod 关键字标记的方法或类查询。

重要提示：在大多数情况下，Web 方法应该是实例方法。在 Web 方法中，通常需要设置 Web 服务实例的属性并调用 Web 服务实例的方法（如后面的主题中所述）以微调方法的行为。由于类方法无法完成这些任务，因此类方法通常不适合作为 Web 方法。

• 对于任何 Web 方法，请确保方法签名中的每个值都有 XML 映射。例如，假设方法具有以下签名：

Method MyWebMethod(myarg as ClassA) as ClassB [ WebMethod ]

在这种情况下，ClassA 和 ClassB 都必须具有 XML 表示形式。在大多数情况下，这意味着它们的超类列表必须包含 %XML.Adaptor;请参阅将对象投影到 XML。 SOAP 支持为集合和流提供特殊处理，如本列表后面所述。

Web 方法可以像普通方法一样指定 ByRef 和 Output 关键字。 （有关这些关键字的信息，请参阅方法。）

• 考虑这些参数和返回值中可能携带的值。 XML 不允许非打印字符，特别是 ASCII 32 以下的字符（XML 中允许的回车符、换行符和制表符除外）。

如果需要包含任何不允许的非打印字符，请将类型指定为 %Binary、%xsd.base64Binary（等效）或子类。导出到 XML 时，该值会自动转换为 Base–64 编码（或导入时自动从 Base–64 编码转换）。

• 不要依赖方法签名来指定参数的默认值。如果这样做，默认值将被忽略并使用空字符串。例如，考虑以下方法：

Method TestDefaults(val As %String = "Default String") As %String [ WebMethod ]

当作为 Web 方法调用此方法时，如果不提供参数，则使用空字符串，并忽略值“默认字符串”。

相反，在方法实现开始时，测试一个值并使用所需的默认值（如果适用）。一种技术如下：

 if arg="" {
   set arg="Default String"
 }

可以照常在方法签名中指示默认值，但这纯粹是为了提供信息，不会影响 SOAP 消息。

• 对于 Web 方法中的任何必需参数，请在方法签名中指定 REQUIRED 属性参数。例如：

Method MyWebMethod(myarg as ClassA(REQUIRED=1)) as ClassB [ WebMethod ]

默认情况下，任何继承的方法都被视为普通方法，即使超类将它们标记为 Web 方法（但请参阅子类化现有 Web 服务）。