步骤 3：实现 Echo 适配器的连接

项目
07/21/2023

第 3 步（共 9 ）

完成时间： 45 分钟

在此步骤中，你将实现 Echo 适配器的连接功能。根据 WCF LOB 适配器 SDK，在连接到目标系统时，必须实现以下抽象类和接口。

Microsoft.ServiceModel.Channels.Common.ConnectionUri
Microsoft.ServiceModel.Channels.Common.IConnection
Microsoft.ServiceModel.Channels.Common.IConnectionFactory

适配器开发向导不从上述抽象类和接口派生，而是自动生成三个派生类：EchoAdapterConnection、EchoAdapterConnectionUri 和 EchoAdapterConnectionFactory。除了创建类外，每个类都有一个引发特定异常 System.NotImplementedException的默认方法。此语句提醒开发人员实现每个类。实现类时，必须删除此异常引发语句。

在下一部分中，将更新这三个类，以便更好地了解如何处理连接、URI 结构是什么，以及如何以编程方式检索各种 URI 元素，然后在适配器中使用这些元素。

先决条件

在开始此步骤之前，必须已成功完成步骤 2：对适配器和连接属性进行分类。你应该对、 Microsoft.ServiceModel.Channels.Common.IConnectionFactory和 Microsoft.ServiceModel.Channels.Common.ConnectionUri 类有一个清晰的了解Microsoft.ServiceModel.Channels.Common.IConnection。

适配器开发向导生成三个派生类：EchoAdapterConnection、EchoAdapterConnectionUri 和 EchoAdapterConnectionFactory。下面简要概述了与每个方法关联的方法。

EchoAdapterConnection

根据适配器的复杂性，可能需要实现以下五种方法。对于 Echo 适配器，不支持大多数适配器，因为 Echo 适配器示例不涉及任何目标系统。

方法	说明
public void Close (TimeSpan timeout)	关闭与目标系统的连接。 Echo 适配器使用此方法仅将跟踪事件添加到跟踪侦听器。
public bool IsValid (TimeSpan timeout)	返回一个值，该值指示连接是否仍然有效。 Echo 适配器不支持。
public void Open (TimeSpan timeout)	打开与目标系统的连接。回显适配器不适用。但是，此示例演示如何使用名为 enableAuthentication 的 URI 元素来要求用户提供用户名。
public void ClearContext ()	清除连接的上下文。当连接设置回连接池时，将调用此方法。 Echo 适配器不支持。
public void Abort ()	中止与目标系统的连接。 Echo 适配器不支持。

EchoAdapterConnectionFactory

连接工厂负责创建连接。默认情况下，只有在连接到目标系统时，才必须修改此类。尽管 Echo 适配器不涉及任何目标系统，但它演示如何在连接需要用户身份验证时使用名为 enableAuthentication 的自定义 URI 元素。

注意

enableAuthentication 不是关键字 (keyword) ，它只是一个变量名称。因此，可以为它选择任何名称。

EchoAdapterConnectionUri

这表示对目标系统的连接字符串。

方法	说明
公共重写 URI	获取并设置 URI。获取以生成 Uri 字符串，并将设置为分析 Uri 字符串。
public EchoAdapterConnectionUri ()	初始化 ConnectionUri 类的新实例。
public override string SampleUriString	返回 EchoAdapter.SCHEME + “：//{hostname}/{application}？enableAuthentication={True\|False}”。此返回字符串在“添加适配器服务引用插件”工具中显示为示例，如下图所示。

显示“添加适配器服务”对话框的屏幕截图。

Echo 适配器连接 URI

示例回显适配器连接 URI 描述为：EchoAapter.SCHEME：//{hostname}/{application}？enableAuthentication={true|false}

由于 EchoAapter.SCHEME 为 echov2，因此连接 URI 为：

echo2：//lobhostname/lobapplication？enableAuthentication={true|false}

当 enableAuthentication=false 时，可以读取以前的连接 URI，如下所示：

使用 echov2 传输架构转到名为 lobhostname 的计算机，其中一个名为 lobapplication 且不需要任何身份验证的应用程序正在等待连接。

或者，当 enableAuthentication=true 时，按如下所示读取连接：

使用 echov2 传输架构，转到名为 lobhostname 的计算机，其中名为 lobapplication 的应用程序要求身份验证正在等待连接。对于 Echo 适配器，只需要用户名。

使用定义的 URI，可以编程方式使用它并对其进行分析，以便进行连接和配置。如果连接需要敏感数据（如用户名和密码），请不要在 URI 中包含此类信息。而是在对象中添加 System.ServiceModel.Description.ClientCredentials 此类信息。添加的代码示例演示如何执行此操作。

在以下代码中，Echo 适配器通过两种方式构造 URI，以显示适配器如何使用各种 URI 元素来修改适配器功能。

echo2：//lobhostname/lobapplication？enableAuthentication=[true|false]

echo2：//lobhostname/lobapplication？enableAuthentication=[true|false]&echoInUpperCase=true

检索 URI 元素

可以分析 Echo 适配器 URI echo2：//lobhostname/lobapplication？enableAuthentication=false&echoInUpperCase=false 中的每个 URI 元素。下表列出了 URI 元素值和关联的方法：

URI 元素值	方法
lobhostname	`System.Uri.Host%2A` 检索主机名
Lobapplication	`System.Uri.AbsolutePath%2A` 检索目标应用程序名称
enableAuthentation=false	GetQueryStringValue (“enableAuthentication”) 使用此 URI 元素验证用户凭据注意： GetQueryStringValue 是在中定义的静态方法 `Microsoft.ServiceModel.Channels.Common.ConnectionUri`
echoInUpperValue=false	GetQueryStringValue (“echoInUpperValue”) 使用此 URI 元素可将传入字符串转换为大写。

EnableAuthentication URI 元素

目标系统通常需要提供客户端凭据来建立与目标系统的连接。如前所述，Echo 适配器不涉及任何目标系统。尽管作为示例，它演示了如何使用名为 enableAuthentication 的自定义 URI 元素来提供凭据。

 public class EchoAdapterConnection : IConnection   
{  
….  
   public void Open(TimeSpan timeout)  
  {  
    // only validate the credentials if EnableAuthentication  
    // connection property value is true  
    if (this.ConnectionFactory.ConnectionUri.EnableAuthentication)  
    {  
        // this adapter expects a value in username  
        if (this.connectionFactory.ClientCredentials != null &&  
            string.IsNullOrEmpty(this.connectionFactory.ClientCredentials.UserName.UserName))  
        {  
            throw new CredentialsException("Username is expected.");  
        }  
  }  
}

代码检查 enableAuthentication 是否为 true 以及是否未提供用户名;如果未提供用户名，则会引发异常，该异常由“添加适配器服务引用”插件工具捕获，如下所示：

显示未提供用户名时引发的异常的屏幕截图。

若要提供用户名，可以在“添加适配器服务引用插件”工具的“配置适配器”对话框中输入该用户名，如下图所示：

显示“配置适配器”对话框的屏幕截图。

EchoInUpperCase URI 元素

EchoInUpperCase URI 元素可以像布尔标志一样进行引用。如果该标志为 true，则适配器会将 EchoStrings 操作的输入字符串转换为大写。

若要更改 echoInUpperCase URI 元素的默认值，请使用“添加适配器服务引用插件”中配置适配器的“URI 属性”选项卡，如下所示。

显示 EchoInUpperCase URI 元素的屏幕截图。

更新 EchoAdapterConnection

实现 EchoAdapterConnection 类的 IsValid、Open 和 Close 方法。

更新 EchoAdapterConnection 类

在 解决方案资源管理器 中，双击EchoAdapterConnection.cs文件。
在 Visual Studio 编辑器中，右键单击编辑器中的任意位置，在上下文菜单中，指向“ 大纲显示”，然后单击“ 停止大纲显示”。
在 Visual Studio 编辑器中，找到 IsValid 方法。在 IsValid 方法中，将现有实现替换为以下实现：
```
return true;  
```

在 Visual Studio 编辑器中，找到 Open 方法。在 Open 方法中，将现有实现替换为以下实现。这将演示如何使用 URI enableAuthentication 元素来确保提供用户名：

// only validate the credentials if EnableAuthentication  
// connection property value is true  
if (this.ConnectionFactory.ConnectionUri.EnableAuthentication)  
{  
    // this adapter expects a value in username  
    // it just logs the credentials in the trace file  
    if (this.connectionFactory.ClientCredentials != null &&  
        string.IsNullOrEmpty(this.connectionFactory.ClientCredentials.UserName.UserName))  
    {  
        throw new CredentialsException("Username is expected.");  
    }  
    // got the username, log it in trace file  
    EchoAdapterUtilities.Trace.Trace(System.Diagnostics.TraceEventType.Information, "EchoAdapterConnection::Open", "Username is " + this.connectionFactory.ClientCredentials.UserName.UserName);  
}  
EchoAdapterUtilities.Trace.Trace(System.Diagnostics.TraceEventType.Information, "EchoAdapterConnection::Open", "Connection successfully established!");

在 Visual Studio 编辑器中，找到 Close 方法。在 Close 方法中，添加以下单个语句：

EchoAdapterUtilities.Trace.Trace(System.Diagnostics.TraceEventType.Information, "EchoAdapterConnection::Close", "Connection successfully closed!");

更新 EchoAdapterConnectionFactory

实现 EchoAdapterConnectionFactory 构造函数，并添加两个名为 ClientCredentials 和 ConnectionUri 的属性。

更新 EchoAdapterConnectionFactory 类

在 解决方案资源管理器 中，双击EchoAdapterConnectionFactory.cs文件。
在 Visual Studio 编辑器中，右键单击编辑器中的任意位置，在上下文菜单中，指向“ 大纲显示”，然后单击“ 停止大纲显示”。

在 Visual Studio 编辑器中，找到 “专用字段” 区域。添加以下单个语句：

private EchoAdapterConnectionUri connectionUri;

专用字段列表应与以下内容匹配：

// Stores the client credentials  
private ClientCredentials clientCredentials;  
// Stores the adapter class  
private EchoAdapter adapter;  
private EchoAdapterConnectionUri connectionUri;

在 Visual Studio 编辑器中，找到 EchoAdapterConnectionFactory 方法。在 EchoAdapterConnectionFactory 构造函数方法中，在“}”之前添加以下单个语句作为最后一个语句。

this.connectionUri = connectionUri as EchoAdapterConnectionUri;

EchoAdapterConnectionFactory 方法的实现应与以下内容匹配：

/// <summary>  
/// Initializes a new instance of the EchoAdapterConnectionFactory class  
/// </summary>  
public EchoAdapterConnectionFactory(ConnectionUri connectionUri  
    , ClientCredentials clientCredentials  
    , EchoAdapter adapter)  
{  
    this.clientCredentials = clientCredentials;  
    this.adapter = adapter;  
    //added  
    this.connectionUri = connectionUri as EchoAdapterConnectionUri;  
}

在 Visual Studio 编辑器中，找到 “公共属性” 区域。添加以下代码：

/// <summary>  
/// Returns the client credentials  
/// </summary>  
public ClientCredentials ClientCredentials  
{  
    get  
    {  
        return this.clientCredentials;  
    }  
}  

/// <summary>  
/// Returns the Connection Uri for this adapter  
/// </summary>  
public EchoAdapterConnectionUri ConnectionUri  
{  
    get  
    {  
        return this.connectionUri;  
    }  
}

更新 EchoAdapterConnectionUri

实现 EchoAdapterConnectionUri 默认构造函数、EchoAdapterConnectionUri (Uri) 重载构造函数和公共重写 Uri 属性。

更新 EchoAdapterConnectionUri 类

在 解决方案资源管理器 中，双击EchoAdapterConnectionUri.cs文件。
在 Visual Studio 编辑器中，右键单击编辑器中的任意位置，在上下文菜单中，指向“ 大纲显示”，然后单击“ 停止大纲显示”。
在 Visual Studio 编辑器中，找到 “构造函数” 区域。在 EchoAdapterConnectionUri () 默认构造函数中，添加以下语句：
```
Uri = new Uri("echov2://lobhostname/lobapplication?enableauthentication=False");  
```
在 Visual Studio 编辑器中的 EchoAdapterConnectionUri (Uri uri) 重载构造函数，并添加以下语句：
```
Uri = uri;  
```
EchoAdapterConnectionUri (Uri) 方法的实现应与以下内容匹配：
```
public EchoAdapterConnectionUri(Uri uri)  
    : base()  
{  
    Uri = uri;  
}  
```

在 Visual Studio 编辑器中 ，在公共重写 Uri 方法 内，将现有替换为以下逻辑。 get 使用 echoInUpperCase 或不使用它生成 Uri。集分析 URI 以检索主机名、数据库名称和查询值。

get  
{  
    // Build the uri  
    if (String.IsNullOrEmpty(this.hostname)) throw new InvalidUriException("Invalid target system host name.");  
    if (String.IsNullOrEmpty(this.application)) throw new InvalidUriException("Invalid target system data source name.");  
    if (EchoInUpperCase)  
    {  
        // build the uri with echoInUpperCase= query string  
        return new Uri(EchoAdapter.SCHEME + "://" + Hostname + "/" + Application + "?" + "enableAuthentication=" + EnableAuthentication + "&" + "echoInUpperCase=" + echoInUpperCase);  
    }  
    else  
    {  
        // build the uri without echoInUpperCase= query string  
        return new Uri(EchoAdapter.SCHEME + "://" + Hostname + "/" + Application + "?" + "enableAuthentication=" + EnableAuthentication);  
    }  
}  
set  
{  
    // Parse the uri  
    String[] enableAuthValue = GetQueryStringValue(value, "enableAuthentication");  
    if (enableAuthValue.Length > 0) this.enableAuthentication = Boolean.Parse(enableAuthValue[0]);  
    String[] echoInUpperValue = GetQueryStringValue(value, "echoInUpperCase");  
    if (echoInUpperValue.Length > 0) this.echoInUpperCase = Boolean.Parse(echoInUpperValue[0]);  

    this.hostname = value.Host;  
    String[] applicationValue = value.AbsolutePath.Split('/');  
    if (applicationValue.Length > 1) this.Application = applicationValue[1];  
}

在 Visual Studio 的“ 文件 ”菜单上，单击“ 全部保存”。
在 “生成” 菜单上，单击 “生成解决方案” 。应成功编译项目。否则，请确保已执行上述每个步骤。

注意

保存所做的工作。此时可以安全地关闭 Visual Studio，也可以转到下一步：步骤 4：实现 Echo 适配器的元数据浏览处理程序。

我只是做什么？

你实现了 Echo 适配器的连接。你了解了 WCF LOB 适配器 SDK 的连接组件、连接 URI 的基本结构、如何以编程方式分析 URI 元素，以及如何使用 URI 元素更改适配器功能。

后续步骤

实现元数据浏览、搜索和解析功能，以及出站消息交换。最后，生成并部署适配器。

另请参阅

步骤 4：实现 Echo 适配器的元数据浏览处理程序
 教程 1：开发 Echo 适配器

通过

步骤 3：实现 Echo 适配器的连接

先决条件

EchoAdapterConnection

EchoAdapterConnectionFactory

EchoAdapterConnectionUri

Echo 适配器连接 URI

检索 URI 元素

EnableAuthentication URI 元素

EchoInUpperCase URI 元素

更新 EchoAdapterConnection

更新 EchoAdapterConnection 类

更新 EchoAdapterConnectionFactory

更新 EchoAdapterConnectionFactory 类

更新 EchoAdapterConnectionUri

更新 EchoAdapterConnectionUri 类

我只是做什么？

后续步骤

另请参阅

反馈

其他资源

通过

步骤 3：实现 Echo 适配器的连接

先决条件

Connection-Related 类

EchoAdapterConnection

EchoAdapterConnectionFactory

EchoAdapterConnectionUri

Echo 适配器连接 URI

检索 URI 元素

EnableAuthentication URI 元素

EchoInUpperCase URI 元素

更新 EchoAdapterConnection

更新 EchoAdapterConnection 类

更新 EchoAdapterConnectionFactory

更新 EchoAdapterConnectionFactory 类

更新 EchoAdapterConnectionUri

更新 EchoAdapterConnectionUri 类

我只是做什么？

后续步骤

另请参阅

反馈

其他资源