外部化 Web 服务文档

• 下载源代码文件 - 14.4 KB
• 下载演示项目 - 21.7 Kb

引言

Visual Studio .NET 为我们提供了一种简单的机制，可以通过使用属性来为 Web 服务添加文档。应用于类的 WebService 属性有一个名为 Description 的属性，可用于概述其用途。同样，应用于方法的 WebMethod 属性也有一个 Description 属性。

以这种方式记录 Web 服务存在一些局限性。首先，当需要提供任何详细信息时，它会变得难以管理。例如，添加参数和值的表意味着需要大量连接的字符串，其中包含难以阅读的转义 HTML。其次，这种方法不适合让翻译人员、技术文档编写人员和编辑人员处理文档，因为他们需要访问代码。第三，页面样式是固定的，可能不符合您的企业形象。

本文通过将文档和样式表移出实现，放入独立文件中来解决上述问题。

背景

默认情况下，所有 Web 服务的文档都由 .NET Framework 配置目录（通常命名为 C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\CONFIG）下的一个名为 DefaultWsdlHelpGenerator.aspx 的页面生成。

当 DefaultWsdlHelpGenerator.aspx 加载时，其 Page.Context 属性会填充一个 ServiceDescriptionCollection，该集合以编程方式描述当前 Web 服务。

ServiceDescriptionCollection 中的每个项都是一个 ServiceDescription，它有一个 Documentation 属性。此值是从 Web 服务类 WebService 属性中的 Description 属性的值自动设置的。 DefaultWsdlHelpGenerator.aspx 将此值输出为 Web 服务的描述。

每个 ServiceDescription 包含一个 Port 的集合，而每个 Port 又包含一个 Operation 的集合。每个 Operation 映射到类中标记有 WebMethod 属性的方法。 Operation 有一个 Documentation 属性，如果 WebMethod 属性的 Description 属性已设置，则该属性会设置。 DefaultWsdlHelpGenerator.aspx 将这些值输出为 Web 服务上每个操作的描述。

提出的解决方案

Microsoft 提供了一种方法，可以按计算机或按应用程序覆盖默认文档生成。关键在于像下面这样编辑 web.config，其中 MyServiceDescriptionGenerator.aspx 是您想用于文档的页面名称。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.web>
    <webServices>
      <wsdlHelpGenerator href="MyServiceDescriptionGenerator.aspx"/>
    </webServices>
  </system.web>
</configuration>

修改 web.config 以使用不同的 aspx 文件足够简单，但事情变得复杂，因为该文件还负责生成用于 SOAP 和 HTTP 协议的示例代码。因此，我们不能简单地将文件替换为记录 Web 服务所需的 HTML，因为我们将不再有为 Web 服务使用者提供示例的机制。

此解决方案复制了现有的 DefaultWsdlHelpGenerator.aspx，并进行了外部化文档和样式表所需的更改。这些更改的意图是尽可能地不干扰，以便更容易地采用新版本的 DefaultWsdlHelpGenerator.aspx。

更改总结如下：

• 外部化样式表。
• 将 DefaultWsdlHelpGenerator.aspx 中的代码移到代码隐藏文件中。
• 添加名为 serviceDocumentation 和 operationDocumentationCollection 的成员变量以保存新文档。
• 创建一个名为 LoadDocumentation 的新方法来加载外部文档。
• 修改 Page_Load 以调用 LoadDocumentation，并用新文档更新默认文档。

新代码的大部分内容位于 LoadDocumentation 中。此方法尝试查找一个与 Web 服务同名但后缀为 Documentation.xml 的文件。示例项目使用 Esendex SMS Web 服务，该服务在 SendService.asmx 文件中实现，并有一个对应的文件名为 SendServiceDocumentation.xml。如果找不到外部文档文件，该方法将返回，并允许处理继续使用框架提供的默认文档。

使用代码

要使用的新的文档生成器在您的代码中，请执行以下操作：

• 将 ServiceDescriptionGenerator.aspx 和 WebServiceDocumentation.css 文件添加到您的项目中。
• 更改您应用程序的 web.config 以引用新的服务描述生成器，如上所述并在示例项目中所示。
• 创建一个包含您文档的新 XML 文件。该文件应以您的 WebService.asmx 文件命名，但后缀为 Documentation.aspx，例如：WebServiceDocumentation.aspx。