在 .NET 环境下访问 SOAP 服务

在 .NET 环境下访问 SOAP 服务

SOAP 服务有着悠久的历史，目前仍然存在大量的 SOAP 服务，它是基于 HTTP 协议和 XML 技术的简单对象访问协议。

在 .NET Framework 时代，访问 SOAP 服务还是比较方便的，我们既可以使用 wsdl.exe 这个工具，也可以使用集成在 Visual Studio 的项目中的工具来生成服务代理，这个代理需要添加对 System.WebService 程序集的引用，它派生自 System.Web.Services.Protocols.SoapHttpClientProtocol，帮助我们访问 SOAP 服务。

在 .NET 时代，很多时候我们仍然需要访问现存的 SOAP 服务，使用的工具和所基于的库发生了一些变化。

首先，我们需要获取 SOAP 服务的定义 通常我们可以通过访问某个服务端点来获得它，对于大多数的 SOAP 服务来说，它会有一个 WSDL 的部分。例如，微软报表服务的管理端点就是 https://myserver/ReportServer/ReportService2010.asmx?wsdl ，也可以通过访问此类端点并保存获得的 WSDL 到一个文件中。

我们这里就使用这个 Reporting Service 2010 进行说明。

如果你希望使用交互工具的话，Visual Studio 中提供了集成的 使用 WCF Web Service Reference Provider 工具。你可以在项目上点击右键，选择 Add -> Connected Service，然后在 Service Reference (OpenAPI, gRPC, WCF Web Service) 的卡片上点击 + 来添加。后面的步骤与以前的工具就是一致的。

如果你希望自己完成，那请继续和我们一起前进。

第二步，安装用于 .NET 的 dotnet-svcutil NuGet 包。

dotnet tool install --global dotnet-svcutil

直接执行它可以看到如下输出

> dotnet-svcutil
Microsoft (R) WCF Service Model Proxy Generation Tool for .Net Core platform
[Microsoft.Tools.ServiceModel.Svcutil, Version 2.1.0]
Copyright (c) Microsoft Corporation.  All rights reserved.

This tool collects information about how it is used in order to improve the tool. This functionality can be disabled by setting the environment variable "DOTNET_SVCUTIL_TELEMETRY_OPTOUT" to 1.

Error: No valid input specified. Specify either a service url or a wsdl file.

If you would like more help, type "dotnet-svcutil -h"

and

 minimum supported framework versions are as follows: netcoreapp1.0, netstandard1.3 and net4.5.

执行安装的 dotnet-svcutil 来生成客户端代理。

dotnet-svcutil https://<Server Name>/ReportServer/ReportService2010.asmx?wsdl

第三步，生成了什么

针对我们使用的 ReportingService201 来说，首先工具帮我们生成了访问该服务的接口 ReportingService2010Soap

public interface ReportingService2010Soap
{
   // ...
}

实现该接口的类型 ReportingService2010SoapClient

public partial class ReportingService2010SoapClient : System.ServiceModel.ClientBase<ServiceReference.ReportingService2010Soap>, ServiceReference.ReportingService2010Soap
{
   // ...
}

需要注意的是该类是一个分部类 partial 类。这意味着我们可以在自己的代码中定义另外一部分，以对生成类进行扩展。

在类定义的第一部分是一个特殊的分部方法 ConfigureEndpoint。方法的注释中这样说：

实现此分部方法以配置此服务端点。

在后面看到的生成的构造函数中，会调用此方法。所以，我们可以在自定义的分部类中，定义实际的此方法来配置该 Web 服务端点。

/// <summary>
/// Implement this partial method to configure the service endpoint.
/// </summary>
/// <param name="serviceEndpoint">The endpoint to configure</param>
/// <param name="clientCredentials">The client credentials</param>
static partial void ConfigureEndpoint(System.ServiceModel.Description.ServiceEndpoint serviceEndpoint, System.ServiceModel.Description.ClientCredentials clientCredentials);

同时，该类还提供了 4 个构造函数。其中前面的 3 个都会调用这个 ConfigureEndpoint() 方法来配置端点。但是，最后一个没有调用这个方法。

public ReportingService2010SoapClient(EndpointConfiguration endpointConfiguration) :
        base(ReportingService2010SoapClient.GetBindingForEndpoint(endpointConfiguration), ReportingService2010SoapClient.GetEndpointAddress(endpointConfiguration))
{
    this.Endpoint.Name = endpointConfiguration.ToString();
    ConfigureEndpoint(this.Endpoint, this.ClientCredentials);
}

public ReportingService2010SoapClient(EndpointConfiguration endpointConfiguration, string remoteAddress) :
        base(ReportingService2010SoapClient.GetBindingForEndpoint(endpointConfiguration), new System.ServiceModel.EndpointAddress(remoteAddress))
{
    this.Endpoint.Name = endpointConfiguration.ToString();
    ConfigureEndpoint(this.Endpoint, this.ClientCredentials);
}

public ReportingService2010SoapClient(EndpointConfiguration endpointConfiguration, System.ServiceModel.EndpointAddress remoteAddress) :
        base(ReportingService2010SoapClient.GetBindingForEndpoint(endpointConfiguration), remoteAddress)
{
    this.Endpoint.Name = endpointConfiguration.ToString();
    ConfigureEndpoint(this.Endpoint, this.ClientCredentials);
}

public ReportingService2010SoapClient(System.ServiceModel.Channels.Binding binding, System.ServiceModel.EndpointAddress remoteAddress) :
        base(binding, remoteAddress)
{
}

在项目中，需要添加下面的 NuGet 包

<ItemGroup>
		<PackageReference Include="System.ServiceModel.Http" Version="4.10.*" />
		<PackageReference Include="System.ServiceModel.Security" Version="4.10.*" />
</ItemGroup>

第 4 步，使用生成的代理

我们通过使用第 4 个构造函数来访问这个服务。

Reporting Service 使用的是基本的 SOAP 服务，同时使用 Windows 验证进行保护。所以使用 BasicHttpBinding，并配置 Ntlm 认证协议。

BasicHttpBinding binding = new BasicHttpBinding();
binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;
binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Ntlm;

TimeSpan timeout = TimeSpan.FromMinutes(5);
binding.OpenTimeout = timeout;
binding.CloseTimeout = timeout;
binding.SendTimeout = timeout;
binding.ReceiveTimeout = timeout;

配置访问端点

String endpointurl = "http://myserver/ReportServer/reportservice2010.asmx";
EndpointAddress endpoint = new EndpointAddress(endpointurl);

var service = new ReportingService2010SoapClient(binding, endpoint);

配置客户端的 Windows 认证账号

service.ClientCredentials.Windows.ClientCredential.UserName = "username";
service.ClientCredentials.Windows.ClientCredential.Password = "password";
service.ClientCredentials.Windows.ClientCredential.Domain = "domain";

好了，现在就可以访问服务了。

第 5 步，使用自定义的分部类来创建 Soap 的客户端

通过上面的介绍，可以看到创建一个客户端实例还是要做一些细致的准备的。我们可以通过自定义的分部类来封装这一部分，通过提供一个扩展出来的方法 GetSoapClientInstance() 来直接获得此实例。

public partial class ReportingService2010SoapClient
{
        public static ReportingService2010SoapClient GetSoapClientInstance() {
            String endpointurl = "http://apxse07.advent.com/ReportServer/reportservice2010.asmx";

            BasicHttpBinding binding = new BasicHttpBinding();
            binding.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;
            binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Ntlm;

            TimeSpan timeout = TimeSpan.FromMinutes(5);
            binding.OpenTimeout = timeout;
            binding.CloseTimeout = timeout;
            binding.SendTimeout = timeout;
            binding.ReceiveTimeout = timeout;

            EndpointAddress endpoint = new EndpointAddress(endpointurl);

            var service = new ReportingService2010SoapClient(binding, endpoint);

            service.ClientCredentials.Windows.ClientCredential.UserName = "Axyssu";
            service.ClientCredentials.Windows.ClientCredential.Password = "June25!!";
            service.ClientCredentials.Windows.ClientCredential.Domain = "Advent";

            return service;
        }
}

这样，我们可以使用下面的代码来得到一个客户端代理的实例：

var soapClient = ReportingService2010SoapClient.GetSoapClientInstance();

第 6 步，访问 Reporting Service 2010 获得服务器上的文件列表。

在 Reporting Service 上包含多种资源，Report 只是其中的一种。Reporting Service 的 SOAP 服务提供了通用的方法 FindItems()，可以定义一个通用的方法来支持获得资源的列表。

方法需要两个参数：一个是资源的类型，一个是目标文件夹。

在生成的代码中，已经包含了请求 SOAP 服务的 Request 定义和 Response 定义，我们需要使用它们来访问 SOAP 服务。

private string[] GetAllOfType(string typeName, string folder)
{
    SearchCondition[] conditions = new SearchCondition[0];
    Property[] options = new Property[0];

    FindItemsRequest request = new FindItemsRequest();
    request.Folder = folder;
    request.BooleanOperator = BooleanOperatorEnum.And;
    request.SearchOptions = options;
    request.SearchConditions = conditions;

    FindItemsResponse response = this.FindItems(request);
    CatalogItem[] items = response.Items;

    List<string> itemNames = new List<string>();

    if (items != null)
        foreach (CatalogItem ci in items)
            if (ci.TypeName == typeName)
                itemNames.Add(ci.Name);

    return itemNames.ToArray();
}

在创建了 GetAllOfType() 方法之后，我们可以编写获得服务器上部署的报表列表了。

public string[] GetAllReports(string folder)
{
    return GetAllOfType("Report", folder);
}

参考资料

• WCF dotnet-svcutil tool for .NET Core
• SAP PO SOAP Web Service with .NET Core client
• The HTTP request is unauthorized with client authentication scheme 'Ntlm'. The authentication header received from the server was 'Negotiate, NTLM'