自定义 Web 服务客户端代理类的注意事项

项目
08/18/2008

更新：2007 年 11 月

在分布式系统设计器中，应用程序上的使用方终结点表示提供方终结点的可配置连接点。在部署由这些应用程序组成的系统定义的实例时，将用任何已连接的提供方终结点的地址配置这些应用程序上的使用方终结点。有关更多信息，请参见应用程序终结点概述和应用程序系统概述。

对于 Web 服务使用方终结点，这需要使用“动态”Web 服务客户端代理类，在运行时从适当的应用程序配置文件项检索已连接的 Web 服务提供方终结点的 URL。

说明：
对于支持实现的应用程序，当您从应用程序关系图实现该应用程序时，Visual Studio 会为它生成一个配置文件。配置文件作为应用程序项目的一部分包含在解决方案资源管理器中。有关更多信息，请参见如何：实现应用程序关系图上的应用程序。

默认情况下，应用程序设计器为 ASP.NET、Windows 和 Office 应用程序上的这些 Web 服务使用方终结点生成 Web 引用。然后，这些 Web 引用创建具有对应配置文件项的适当动态代理类。

说明：
如果您在应用程序或所引用的类库中使用静态 Web 引用，则这些 Web 引用将不会被应用程序设计器检测到，而且将不会被可视化为 Web 服务使用方终结点，即使它们可以正常工作也是如此。建议您总是使用动态 Web 引用，即使您不打算在部署时更改 Web 服务 URL 也是如此。

以下各节包含有关使用自定义 Web 服务客户端代理类（而非动态代理类）的更多信息：

将自定义的 Web 服务客户端代理类表示为 Web 服务使用方终结点
与 Windows 和 Office 应用程序一起使用的自定义 Web 服务代理客户端类的配置文件项
与 ASP.NET 应用程序一起使用的自定义 Web 服务代理类的配置文件项
从 Visual Studio .NET 2003 迁移 Web 引用和自定义 Web 服务客户端代理类

将自定义的 Web 服务客户端代理类表示为 Web 服务使用方终结点

应用程序设计器支持设计由 Web 引用实现的 Web 服务使用方终结点。但是，只要使用者应用程序的配置文件（App.config 或 Web.config）中存在相应的项，就还可以对手动创建的自定义代理类进行反向工程处理，并将它们可视化为 Web 服务使用方终结点。

Web 服务使用方终结点出现在每个配置文件项的使用者应用程序上，应用程序设计器将这些项标识为表示自定义代理类的 Web 服务 URL 设置。另外，如果配置文件项中的 Web 服务 URL 与应用程序关系图上现有的 Web 服务提供方终结点的 URL 匹配，则还会在使用方终结点与 Web 服务提供方终结点之间出现一个连接。如果不存在匹配的 Web 服务提供方终结点，但可以通过在 URL 末尾追加“?wsdl”或“?disco”来用 URL 定位 Web 服务的有效 WSDL 文件，那么，外部 Web 服务将添加到应用程序关系图中，并连接到 Web 服务使用方终结点。如果无法使用 URL 来定位 WSDL 文件，则 Web 服务使用方终结点将保持未连接状态。

对于 ASP.NET 应用程序和 Windows 或 Office 应用程序来说，表示 Web 服务 URL 设置的配置文件项和应用程序设计器标识它们的方法有所不同。下列准则描述如何确保在每一类应用程序上将自定义代理类正确表示为 Web 服务使用方终结点。

说明：
不遵循这些准则也许仍能生成在运行时正常工作的自定义代理类；但是，这些类将不会被表示为 Web 服务使用方终结点，将不在应用程序关系图上建立连接，将不会针对部署进行验证，将不会在部署报告上报告为终结点，并且当使用任何可用的部署工具时都不能用于终结点配置。

与 Windows 和 Office 应用程序一起使用的自定义 Web 服务代理客户端类的配置文件项

对于与 Windows 和 Office 应用程序一起使用的自定义代理类，Web 服务 URL 设置必须出现在使用者应用程序的 App.config 配置文件的 applicationSettings 项中。不能通过使用设置和约束编辑器来查看或编辑这些设置，因此，必须使用“设置”窗格来创建或编辑这些设置，该窗格可通过右击 Windows 或 Office 应用程序项目并查看该项目的属性来访问。还必须将这些设置指定为 WebServiceURL 或 String 类型。有关更多信息，请参见管理应用程序设置。

说明：
WebServiceURL 类型指定不出现在 App.config 配置文件中；但是，它存储在通常处于隐藏状态的关联设置文件中。如果您将设置手动添加到 App.config 配置文件中，则必须将 WebServiceURL 或 String 类型指定作为一个设置添加到“设置”窗格中。

在“设置”窗格中，如果您将设置指定为 WebServiceURL 类型，则可以为它选择“应用程序”或“用户”范围。更改范围时会将该项相应地移到配置文件的 applicationSettings 或 userSettings 节中。但是，如果您选择将设置指定为 String 类型，则必须选择“应用程序”范围。

提示：
在 App.config 文件中指定 Web 服务 URL 设置时，指定的是 Web 服务的位置，而不是 Web 服务说明或 WSDL 文件的位置。对于基于 .asmx 文件的 Web 服务，Web 服务说明通常与 WSDL 在同一个位置。因此，对于基于 .asmx 文件的 Web 服务，应用程序设计器将假定 Web 服务与 WSDL 文件在同一个位置。如果在该位置找到了 WSDL 文件，则外部 Web 服务会被反向工程到应用程序关系图上并连接到经过反向工程处理的 Web 服务使用方终结点。如果在该位置找不到有效的 WSDL 文件，将仅仅对 Web 服务使用方终结点进行反向工程处理。

在 App.config 文件中指定 Web 服务 URL 设置时，指定的是 Web 服务的位置，而不是 Web 服务说明或 WSDL 文件的位置。对于基于 .asmx 文件的 Web 服务，Web 服务说明通常与 WSDL 在同一个位置。因此，对于基于 .asmx 文件的 Web 服务，应用程序设计器将假定 Web 服务与 WSDL 文件在同一个位置。如果在该位置找到了 WSDL 文件，则外部 Web 服务会被反向工程到应用程序关系图上并连接到经过反向工程处理的 Web 服务使用方终结点。如果在该位置找不到有效的 WSDL 文件，将仅仅对 Web 服务使用方终结点进行反向工程处理。

下面的示例演示在将设置指定为 String 类型时，applicationSettings 项在 Windows 项目的 App.config 配置文件中如何显示：

<applicationSettings>
   <WindowsApplicationName.MySettings>
      <setting name="WindowsApplicationName_Namespace_WebServiceProxyClassName" serializeAs="String"><value>http://WebServiceURL.asmx</value></setting>
   </WindowsApplicationName.MySettings>
</applicationSettings>

对于类型为 WebServiceURL 的项，设置不必与代理类同名。若要在 Windows 或 Office 应用程序上创建 Web 服务使用方终结点，只需按这种方式定义一个配置文件项，并在“设置”窗格中将它指定为 WebServiceURL 或 String 类型即可，即使没有任何自定义代理类与该项关联也是如此。如果删除这样的终结点，将会同时删除该项，但不会删除与之关联的自定义代理类。

与 ASP.NET 应用程序一起使用的自定义 Web 服务代理类的配置文件项

ASP.NET 不提供用来指定配置文件项表示 Web 服务 URL 的方法。因此，应用程序设计器尝试将配置文件项的名称与代理类的名称匹配。下列准则适用于与 ASP.NET 应用程序一起使用的自定义代理类的配置文件项：

只有当在使用者应用程序项目或任何引用的项目或程序集中找到了具有匹配名称的代理类时，才会出现 Web 服务使用方终结点。
如果自定义代理类仅用于 ASP.NET 应用程序，则 Web 服务 URL 应出现在 ASP.NET 应用程序的 Web.config 配置文件的 appSettings 项中。配置文件项的名称必须是完全限定的代理类名称。可通过使用设置和约束编辑器来编辑 Web.config 文件中的 appSettings 项。有关更多信息，请参见设置和约束编辑器和应用设置。
如果自定义代理类用于 Windows 和 Office 应用程序以及 ASP.NET 应用程序，则 Web 服务 URL 应出现在 ASP.NET 应用程序的 Web.config 配置文件的 applicationSettings 项中。配置文件项的名称必须是以项目名称作为前缀的完全限定代理类名称，这是自动生成的 Web 引用使用的默认格式。可通过使用设置和约束编辑器来编辑 Web.config 文件中的 applicationSettings 项。applicationSettings 节不支持在设置名称中使用点 (.) 语法，而是支持使用下划线 (_) 字符。

下面的示例演示 appSettings 项在 Web.config 文件中如何显示：

<appSettings>
   <add key="Namespace.WebServiceProxyClassName" value="https://localhost/WebServiceApplicationName/WebServiceName.asmx"/>
</appSettings>

下面的示例演示 applicationSettings 项在 Web.config 文件中如何显示，该项与在 Windows 或 Office 应用程序的 App.config 文件中使用的项相同。

<applicationSettings>
   <WindowsApplicationName.MySettings>
      <setting name="WindowsApplicationName_Namespace_WebServiceProxyClassName" serializeAs="String"><value>http://WebServiceURL.asmx</value></setting>
   </WindowsApplicationName.MySettings>
</applicationSettings>

删除表示自定义代理类的 Web 服务使用方终结点时，会移除关联的配置文件项，但不会删除关联的代理类。删除或重命名自定义代理类不会移除关联的配置文件项，但会移除对应的使用方终结点，因为具有匹配名称的代理类已不再存在。如果重新添加具有匹配名称的代理类，或者重命名现有的代理类，使其与配置文件项匹配，则会导致终结点重新出现。

从 Visual Studio .NET 2003 迁移 Web 引用和自定义 Web 服务客户端代理类

使用 Visual Studio .NET 2003 添加到 Windows 或 Office 项目中的 Web 引用的关联配置文件项存储在 appSettings 节中，而不是存储在 applicationSettings 节中。当使用转换向导升级 Visual Studio .NET 2003 Windows 或 Office 项目时，Web 引用和自定义代理类不会从 appSettings 节自动迁移到 applicationSettings 节。有关转换向导的更多信息，请参见 Visual Studio 转换向导。

但是，在重新生成代理类时，例如，在更改对应的 Web 服务或手动刷新 Web 引用时，Web 引用会自动迁移。新设置出现在每个 Web 引用的 applicationSettings 节中并由更新后的代理类使用。applicationSettings 节更新后，会在应用程序关系图上出现对应的 Web 服务使用方终结点和连接。有关更多信息，请参见如何：在应用程序关系图中刷新对 Web 服务的 Web 引用。

如果您希望显示自定义代理类的 Web 服务使用方终结点，则必须手动迁移这些类。可通过以下方法来执行此任务：更新代理类以使用 applicationSettings 节，并使用可通过 Windows 或 Office 应用程序项目属性访问的“设置”窗格来添加相应的设置。有关更多信息，请参见管理应用程序设置。

请参见

通过