WCF入门教程
WCF入门教程
本节中包含的主题旨在帮助您快速了解 Windows Communication Foundation (WCF) 编程体验。这些主题要根据本主题底部的列表中的顺序完成。通过学习本教程，您可以初步了解创建 WCF 服务和客户端应用程序所需的步骤。服务是一种构造，它公开一个或多个终结点，其中每个终结点都公开一项或多项服务操作。服务的终结点指定下列信息：服务所在的位置；一个绑定，其中包含客户端必须与服务进行通信的信息；一个协定，用于定义服务向其客户端提供的功能。
在完成本教程中的系列主题之后，您将会得到一个正在运行的服务，以及一个可以调用该服务的操作的客户端。前三个主题描述如何使用协定定义服务，如何实现服务，以及如何在代码中配置服务、承载服务和运行服务。所创建的服务是自承载服务，客户端和服务都在同一计算机上运行。服务使用代码而非配置进行配置。另外还可以将服务承载于 Internet 信息服务 (IIS) 下。有关如何执行此操作的更多信息，请参见“如何：如何：在 IIS 中承载 WCF 服务”。也可以在配置文件中配置服务。有关使用配置文件的更多信息，请参见使用配置文件配置服务。
后三个主题描述如何创建客户端代理，如何配置客户端应用程序，以及如何创建和使用可以访问服务功能的客户端。服务会发布可以访问的元数据，这些数据定义了客户端应用程序与服务操作进行通信所需的构造。WCF 提供了一个ServiceModel Metadata Utility Tool (Svcutil.exe)来自动完成以下过程：访问发布的这些元数据，然后使用这些元数据来构造和配置服务的客户端应用程序。
本节中的所有主题均假定您使用 Visual Studio 2008 作为开发环境。如果您使用的是其他开发环境，请忽略特定于 Visual Studio 的说明。
注意:
如果运行的是 Windows Vista，则必须通过在“开始”菜单上右击 Microsoft Visual Studio 2008，然后选择“以管理员身份运行”的方式来启动 Visual Studio。若要始终以管理员身份启动 Visual Studio 2008，可以创建一个快捷方式，右击该快捷方式，选择“属性”，选择“兼容性”选项卡，然后选中“请以管理员身份运行该程序”复选框。在使用此快捷方式启动 Visual Studio 2008 时，会总是以管理员身份运行。
有关可以下载到硬盘中并运行的示例应用程序，请参见Windows Communication Foundation Samples中的主题。有关专门针对本主题的示例，请参见Getting Started Sample。
有关创建服务和客户端的更深入信息，请参见基本 WCF 编程。
本节内容
如何：定义 Windows Communication Foundation 服务协定
描述如何使用用户定义的接口创建 WCF 协定。协定用于定义服务向外界
提供的功能，并向外界的潜在用户描述如何与服务进行通信。
如何：实现 Windows Communication Foundation 服务协定
描述如何实现服务协定。创建了协定后，必须在一个从定义协定的接口继承的类中实现服务所提供的功能。
如何：承载和运行基本的 Windows Communication Foundation 服务
描述如何在代码中配置服务的终结点，以及如何在控制台应用程序内承载服务和启动服务。若要激活服务，必须在运行时环境中配置和承载服务。
此环境将创建服务并控制其上下文和生存期。
如何：创建 Windows Communication Foundation 客户端
描述如何从 WCF 服务检索用于创建 WCF 客户端的元数据。此过程使用由WCF 提供的ServiceModel Metadata Utility Tool (Svcutil.exe)。
如何：配置基本 Windows Communication Foundation 客户端
描述如何配置使用ServiceModel Metadata Utility Tool (Svcutil.exe)创建的基本客户端。配置客户端需要指定客户端用于访问服务的终结点。如何：使用 Windows Communication Foundation 客户端
描述如何使用ServiceModel Metadata Utility Tool (Svcutil.exe)生成的 WCF 客户端代理来调用服务所提供的功能。
如何：定义服务协定
这是创建基本 Windows Communication Foundation (WCF) 服务和可以调用该服务的客户端所需的六项任务中的第一项任务。有关全部六项任务的概述，请参见入门教程主题。
创建基本 WCF 服务时，第一项任务是定义协定。协定指定服务支持的操作。可以将操作视为一个 Web 服务方法。通过定义 C++、C# 或 VB 接口可创建协定。接口中的每个方法都对应于特定的服务操作。每个接口都必须将ServiceContractAttribute应用于自身，而每个操作都必须将OperationContractAttribute应用于自身。如果接口中的一个方法具有ServiceContractAttribute而没有OperationContractAttribute，则不公开该方法。
在操作过程后面的示例中提供了用于此任务的代码。
使用接口创建 Windows Communication Foundation 协定
1.通过在“开始”菜单中右击“Visual Studio 2008”并选择“以管理员身
份运行”，以管理员身份打开该程序。
2.创建新的控制台应用程序项目。在“新建项目”对话框中，选中“Visual
Basic”或“Visual C#”，并选择“控制台应用程序”模板，并命名为
Service。使用默认的位置。
3.将默认的 Service 命名空间更改为 Microsoft.ServiceModel.Samples。
4.将对System.ServiceModel.dll的引用添加到项目。
1.在“解决方案资源管理器”中，右击项目文件夹下的“引用”文件夹，然后选择
“添加引用”。
2.单击“添加引用”对话框中的“浏览”选项卡，导航到
“c:\Windows\https://www.360docs.net/doc/804601725.html,\Framework\v3.0\Windows Communication
Foundation”，选择“System.ServiceModel.dll”，然后单击“确定”。
注意:
在使用命令行编译器（例如Csc.exe 或Vbc.exe）时，还必须提供程序集的路径。例如，在运行Windows Vista 的计算机上，默认情况下的路径为：Windows\https://www.360docs.net/doc/804601725.html,\Framework\v3.0\Windows Communication Foundation。
5.为System.ServiceModel命名空间添加一个using语句（在 Visual
Basic 中为Imports）。
6.定义一个名为 ICalculator 的新接口，并向该接口应用Namespace值为
“http://Microsoft.ServiceModel.Samples”的
ServiceContractAttribute属性。显式指定命名空间是一种最佳做法，
因为这样可防止将默认命名空间值添加到协定名称。
注意:
使用属性来批注接口或类时，可以从属性名称中去掉“Attribute”部分。因此ServiceContractAttribute将变成[ServiceContract]
7.在接口中为 ICalculator 协定公开的每个操作（加、减、乘和除）声明
一个方法，并对希望作为公共 WCF 协定的一部分公开的每个方法应用
OperationContractAttribute属性。
示例
下面的代码示例演示一个定义服务协定的基本接口。
现在已创建接口。生成该项目以确保不存在编译错误，然后按照如何：实现
Windows Communication Foundation 服务协定中的说明实现接口。有关疑难解
答信息，请参见入门教程疑难解答。
如何：实现服务协定
这是创建基本 Windows Communication Foundation (WCF) 服务和可以调用该服务的客户端所需的六项任务中的第二项任务。有关全部六项任务的概述，请参见入门教程主题。
创建 WCF 服务要求首先创建使用接口定义的协定。有关创建该接口的更多信息，请参见如何：定义 Windows Communication Foundation 服务协定。本示例中显示的下一步骤是实现接口。这涉及到创建一个名为CalculatorService的类，该类实现用户定义的ICalculator接口。在操作过程后面的示例中提供了用于此任务的代码。
实现 WCF 服务协定
1.在定义了 ICalculator 接口的同一文件中创建一个名为
CalculatorService 的新类。CalculatorService 实现 ICalculator 接口。
2.在 CalculatorService 类中实现在 ICalculator 接口中定义的每个方
法。
注意:
已经添加写入输出代码以方便测试。
示例
下面的代码示例演示定义协定的接口和接口的实现。
现在已创建并实现了服务协定。生成该解决方案以确保不存在编译错误，然后按照如何：承载和运行基本的 Windows Communication Foundation 服务中的说明运行服务。有关疑难解答信息，请参见入门教程疑难解答。
编译代码
如果使用的是命令行编译器，则必须引用System.ServiceModel程序集。
如何：承载和运行基本的服务
这是创建基本 Windows Communication Foundation (WCF) 服务和可以调用该服务的客户端所需的六项任务中的第三项任务。有关全部六项任务的概述，请参见入门教程主题。
本主题描述如何运行基本的 Windows Communication Foundation (WCF) 服务。此过程包含以下步骤：
?为服务创建基址。
?为服务创建服务主机。
?启用元数据交换。
?打开服务主机。
在过程后面的以下示例中提供了在此任务中编写的代码的完整清单。将下面的代码添加到 Program 类中定义的 Main() 方法。此类是在您创建 Service 解决方案时生成的。
为服务配置基址
1.为服务的基址创建Uri实例。此 URI 指定 HTTP 方案、本地计算机、端
口号 8000，以及服务协定中为服务命名空间指定的服务路径
ServiceModelSample/Service。
承载服务
1.导入 System.ServiceModel.Description 命名空间。这行代码应该与
using或imports语句的其余部分一起放置在 Program.cs/Program.vb 文件的顶部。
2.创建一个新的ServiceHost实例以承载服务。必须指定实现服务协定和
基址的类型。对于此示例，基址为
http://localhost:8000/ServiceModelSamples/Service，
CalculatorService 为实现服务协定的类型。
3.添加一个捕获CommunicationException的try-catch语句，并在接下
来的三个步骤中将该代码添加到 try 块中。catch 子句应该显示错误信
息，然后调用 selfHost.Abort()。
4.添加公开服务的终结点。为此，必须指定终结点公开的协议、绑定和终结
点的地址。对于此示例，将 ICalculator 指定为协定，将 WSHttpBinding 指定为绑定，并将 CalculatorService 指定为地址。在这里请注意，终
结点地址是相对地址。终结点的完整地址是基址和终结点地址的组合。在
此例中，完整地址是
http://localhost:8000/ServiceModelSamples/Service/CalculatorSer
vice。
5.启用元数据交换。为此，添加服务元数据行为。首先创建一个
ServiceMetadataBehavior实例，将HttpGetEnabled属性设置为true，然后为服务添加新行为。有关发布元数据时出现的安全问题的更多信息，请参见元数据的安全注意事项。
6.打开ServiceHost并等待传入消息。用户按 Enter 键时，关闭
ServiceHost。
验证服务是否正常运行
1.从 Visual Studio 内部运行 service.exe。在 Windows Vista 上运行时，
必须使用管理员特权运行服务。由于 Visual Studio 是使用管理员特权
运行的，因此 service.exe 也是使用管理员特权运行的。也可以启动新
的命令提示，使用管理员特权运行它，并在其中运行 service.exe。
2.打开 Internet Explorer，并浏览到服务的调试页（网址为
http://localhost:8000/ServiceModelSamples/Service）。
示例
下面的示例包括本教程中前面步骤的服务协定和实现，并将服务承载于控制台应用程序中。将以下内容编译为可执行文件 Service.exe。
在编译代码时，务必引用System.ServiceModel.dll。
注意:
此类服务需要在计算机上注册 HTTP 地址以进行侦听的权限。管理员帐户具有此权限，但必须授予非管理员帐户对 HTTP 命名空间的权限。有关如何配置命名空间保留的更多信息，请参见配置 HTTP 和 HTTPS。在 Visual Studio 下运行时，必须使用管理员特权运行 service.exe。
此时服务正在运行。继续执行如何：创建 Windows Communication Foundation 客户端中的步骤。有关疑难解答信息，请参见入门教程疑难解答。
如何：创建客户端
这是创建基本 Windows Communication Foundation (WCF) 服务和可以调用该服务的客户端所需的六项任务中的第四项任务。有关全部六项任务的概述，请参见入门教程主题。
本主题描述如何检索 WCF 服务中的元数据，以及如何使用这些元数据创建可以访问该服务的 WCF 代理。此任务是通过使用 WCF 所提供的ServiceModel Metadata Utility Tool (Svcutil.exe)完成的。此工具可以获取服务的元数据，并使用所选语言生成代理的托管源代码文件。除了创建客户端代理外，该工具还会为客户端创建配置文件，以使客户端应用程序能够连接至其某个终结点上的服务。
客户端应用程序会使用生成的代理创建 WCF 客户端对象。如何：使用 Windows Communication Foundation 客户端中对此过程进行了描述。
在操作过程后面的示例中提供了用于此任务产生的客户端的代码。
创建 Windows Communication Foundation 客户端
1.通过执行以下步骤，在中在当前解决方案中为客户端创建一个新项目：
1.在包含该服务的同一解决方案中的“解决方案资源管理器”（位于
右上角）中，右击当前解决方案（而不是项目），选择“添加”，
然后选择“新项目”。
2.在“添加新项目”对话框中，选择“Visual Basic”或“Visual
C#”，选择“控制台应用程序”模板，然后将其命名为Client。
使用默认的位置。
3.单击“确定”。
2.为项目添加对System.ServiceModel.dll 的引用：
1.在“解决方案资源管理器”中的“Client”项目下右击“引用”
文件夹，然后选择“添加引用”。
2.选择“最近”选项卡，并从列表框选择
“System.ServiceModel.dll”，然后单击“确定”。因为已在本
教程的第一步添加了对该程序集的引用，所以该程序集现在列在
“最近”选项卡中。如果在“最近”选项卡中看不到该程序集，请
选择“浏览”选项卡并导航至
C:\Windows\https://www.360docs.net/doc/804601725.html,\Framework\v3.0\Windows
Communication Foundation，然后从这里选择该程序集。
注意:
在使用命令行编译器（例如 Csc.exe 或 Vbc.exe）时，还必须提供程序集的路径。例如，在运行 Windows Vista 的计算机上，默认情况下的路径为：
Windows\https://www.360docs.net/doc/804601725.html,\Framework\v3.0\Windows Communication Foundation。
3.在生成的 Program.cs 或 Program.vb 文件中为System.ServiceModel
命名空间添加一个using语句（在 Visual Basic 中为Imports）。
Visual Basic
复制代码
Imports System.ServiceModel;
C#
复制代码
using System.ServiceModel;
4.启动在前面的步骤中创建的服务。有关更多信息，请参见如何：承载和
运行基本的 Windows Communication Foundation 服务。
5.通过执行以下步骤，使用适当的开关运行Service Model Metadata
Utility Tool (SvcUtil.exe)以创建客户端代码和配置文件：
1.通过选择“开始”菜单中的“Microsoft Windows SDK”项下的
“CMD Shell”，启动 Windows SDK 控制台会话。
2.导航到要放置客户端代码的目录。如果创建该客户端项目时使用了
默认设置，则目录为 C:\Users\<用户名>\Documents\Visual
Studio 2005\Projects\Service\Client。
3.将命令行工具Service Model Metadata Utility Tool
(SvcUtil.exe)与适当的开关一起使用以创建客户端代码。下面的
示例生成服务的代码文件和配置文件。
[Visual Basic]
复制代码
svcutil.exe /language:vb /out:generatedProxy.vb
/config:app.config
http://localhost:8000/ServiceModelSamples/service
[C#]
复制代码
svcutil.exe /language:cs /out:generatedProxy.cs
/config:app.config
http://localhost:8000/ServiceModelSamples/service
默认情况下，将在一个以服务命名的文件（例如，在本示例中将为
CalculatorService.cs 或 CalculatorService.vb，其扩展名与编
程语言相对应：.vb 对应于 Visual Basic，.cs 对应于 C#）中生
成客户端代理代码。/out开关会将客户端代理文件的名称更改为
generatedProxy.cs。/config开关会将客户端配置文件的名称从
默认的 output.config 更改为 app.config。请注意，这两个文件
都是在 C:\Users\<用户名>\Documents\Visual Studio
2005\Projects\Service\Client 目录中生成的。
6.在 Visual Studio 中将生成的代理添加到该客户端项目中，方法是在
“解决方案资源管理器”中右击该客户端项目，选择“添加”，然后选择“现有项”。然后选择在上一步中生成的generatedProxy.cs文件。
示例
此示例演示由Service Model Metadata Utility Tool (Svcutil.exe)生成的客户端代码。
现在您已经创建了一个 Windows Communication Foundation (WCF) 客户端。请继续执行如何：配置基本 Windows Communication Foundation 客户端中的步骤配置该客户端。有关疑难解答信息，请参见入门教程疑难解答。
如何：配置客户端
这是创建基本 Windows Communication Foundation (WCF) 服务和可以调用该服务的客户端所需的六项任务中的第五项任务。有关全部六项任务的概述，请参见入门教程主题。
本主题要将使用Service Model Metadata Utility (Svcutil.exe)生成的客户端配置文件添加到客户端项目中，并解释客户端配置元素的内容。配置客户端包括指定客户端用于访问服务的终结点。每个终结点都有一个地址、一个绑定和一个协定，所有这些元素都必须在配置客户端的过程中指定。
在过程后面的示例中提供了为客户端生成的配置文件的内容。
配置 Windows Communication Foundation 客户端
1.在 Visual Studio 中，将在前一过程如何：创建 Windows Communication
Foundation 客户端中生成的 App.config 配置文件添加到客户端项目
中。在“解决方案资源管理器”中右击客户端项目，选择“添加”，然后选择“现有项”。然后，从 C:\Users\<用户名>\Documents\Visual
Studio 2005\Projects\Service\Client 目录中选择 App.config 配置
文件。（之所以命名为 App.config 文件，是因为在使用 Svcutil.exe 工
具生成此文件时使用了/config:app.config开关）。单击“确定”。默认情况下，“添加现有项”对话框会筛选出具有 .config 扩展名的所有文件。若要查看这些文件，请从位于“添加现有项”对话框右下角的下拉列表框中选择“所有文件(*.*)”。
2.打开生成的配置文件。Svcutil.exe 会为绑定上的每一项设置都生成值。
下面的示例显示了生成的配置文件。请在
查找
复制代码
address="http://localhost:8000/ServiceModelSamples/Service/Calc ulatorService" binding="wsHttpBinding" bindingConfiguration="WSHttpBinding_ICalculator" contract="Microsoft.ServiceModel.Samples.ICalculator" name="WSHttpBinding_ICalculator"> 此示例配置的终结点可供客户端在访问位于以下地址的服务时使用： http://localhost:8000/ServiceModelSamples/service 终结点元素指定 Microsoft.ServiceModel.Samples.ICalculator 协定 将用于通过系统提供的WsHttpBinding配置的通信。此绑定指定 HTTP 作为传输协议、可互操作安全性以及其他配置详细信息。 3.有关如何在此配置下使用生成的客户端的更多信息，请参见如何：使用 Windows Communication Foundation 客户端。 示例 下面的示例演示为客户端生成的配置文件的内容。 复制代码 closeTimeout="00:01:00" openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00" bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard" maxBufferPoolSize="524288" maxReceivedMessageSize="65536" messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true" allowCookies="false"> maxStringContentLength="8192" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="16384" /> inactivityTimeout="00:10:00" enabled="false" /> proxyCredentialType="None" realm="" /> negotiateServiceCredential="true" algorithmSuite="Default" establishSecurityContext="true" /> address="http://localhost:8000/ServiceModelSamples/Service/Calculator Service" binding="wsHttpBinding" bindingConfiguration="WSHttpBinding_ICalculator" contract="ICalculator" name="WSHttpBinding_ICalculator"> 现在已配置完客户端。请继续执行如何：使用 Windows Communication Foundation 客户端中的步骤。有关疑难解答信息，请参见入门教程疑难解答。 如何：使用客户端 这是创建基本 Windows Communication Foundation (WCF) 服务和可以调用该服务的客户端所需的六项任务中的第六项任务。有关全部六项任务的概述，请参见入门教程主题。 在创建并配置了 Windows Communication Foundation (WCF) 代理后，就可以创建客户端实例，进而编译客户端应用程序并使用它与 WCF 服务进行通信。本主题描述创建和使用 WCF 客户端的过程。此过程执行三个操作：创建 WCF 客户端，从生成的代理调用服务操作，以及在完成操作调用后关闭客户端。 在过程后面的示例中还提供了过程中所讨论的代码。此任务中的代码应该放置在客户端项目中所生成的 Program 类的 Main() 方法中。 使用 Windows Communication Foundation 客户端 1.为要调用的服务的基址创建EndpointAddress实例，然后创建 WCF Client对象。 2.从Client内调用客户端操作。 3.在 WCF 客户端上调用Close并等待，直到用户按 Enter 键终止应用程 序。 示例 下面的示例演示如何创建 WCF 客户端，如何调用客户端操作，以及在完成操作调用后如何关闭客户端。 将生成的 WCF 客户端和下面的代码示例编译为可执行文件 Client.exe。在编译代码时，务必引用System.ServiceModel。 确保在尝试使用客户端之前服务正在运行。有关更多信息，请参见如何：承载和运行基本的 Windows Communication Foundation 服务。 若要启动客户端，请在“开始”菜单中的“Microsoft Windows SDK”项下选择“CMD Shell”，从而启动 Windows SDK 控制台会话。定位至 C:\Users\<用户名>\Documents\Visual Studio 2005\Projects\Service\Client\bin\Debug 目录，键入client，然后按 Enter。操作请求和响应将出现在客户端控制台窗口中，如下所示。 复制代码 Add(100,15.99) = 115.99 Subtract(145,76.54) = 68.46 Multiply(9,81.25) = 731.25 Divide(22,7) = 3.14285714285714 Press 如果看到此输出，则说明成功完成了教程。此示例演示如何在代码中配置 WCF 客户端。有关疑难解答信息，请参见入门教程疑难解答。 入门教程疑难解答 本主题列出使用“入门教程”时最常遇见的问题及其解决方法。 问题： 无法在硬盘上找到项目文件。 解决方案： 在 Windows Vista 中，Visual Studio 将项目文件保存在 c:\users\<用户 名>\Documents\Visual Studio 2005\Projects 下，对于 Windows 的早期版本，保存在 c:\Documents and Settings\<用户名>\My Documents\Visual Studio 2005\Projects 下。 问题： 尝试运行服务应用程序时出现以下错误：HTTP 无法注册 URL http://+:8000/ServiceModelSamples/Service/。进程不具有此命名空间的访问权限（有关详细信息，请参阅配置 HTTP 和 HTTPS（可能为英文网页））。 解决方案： 必须使用管理特权来运行承载 WCF 服务的进程。如果从 Visual Studio 2008 内运行服务，则必须以管理员身份运行 Visual Studio 2008。为此，请单击“开始”，右击“Visual Studio 2008”，然后选择“以管理员身份运行”。如果从命令行提示符运行服务，则必须按类似方式以管理员身份启动命令行提示符。单击“开始”，右击“命令提示符”，然后选择“以管理员身份运行”。 问题： 尝试使用 Svcutil.exe 工具时出现以下错误：“svcutil”不是内部或外部命令，也不是可运行的程序或批处理文件。 解决方案： Svcutil.exe 必须位于系统路径中。最简单的解决方案是使用 Visual Studio 2005 命令提示。单击“开始”，依次选择“所有程序”、“Visual Studio 2008”、“Visual Studio Tools”和“Visual Studio 2008 命令提示”。对于 Visual Studio 2008 中附带的所有工具，此命令提示均能将系统路径设置为正确的位置。 问题： 无法找到由 Svcutil.exe 生成的 app.config 文件。 解决方案： 默认情况下，“添加现有项”对话框仅显示具有以下扩展名的文 件：.cs、.resx、.settings、.xsd 和 .wsdl。通过在“添加现有项”对话框右下角的下拉列表框中选择“所有文件(*.*)”，可以指定您希望查看所有文件类型。 问题： 编译客户端应用程序期间，出现以下语法错误：“CalculatorClient”不包含“<方法名称>”的定义，并且找不到可接受类型为“CalculatorClient”的第一个参数的扩展方法“<方法名称>”(是否缺少 using 指令或程序集引用?) 解决方案： 仅向外界公开标记有ServiceOperationAttribute的那些方法。如果在ICalculator接口的某个方法中省略了ServiceOperationAttribute属性，则当所编译的客户端应用程序调用缺少该属性的操作时，便会收到此错误消息。 问题： 编译客户端应用程序期间，出现以下语法错误：找不到类型或命名空间名称“CalculatorClient”(是否缺少 using 指令或程序集引用?) 解决方案： 如果未将 proxy.cs 或 proxy.vb 文件添加到客户端项目，则会收到此错误。 问题： 未处理的异常：System.ServiceModel.EndpointNotFoundException：无法连接到 http://localhost:8000/ServiceModelSamples/Service/CalculatorService。TCP 错误代码 10061：由于目标计算机主动拒绝，未能建立连接。 解决方案： 如果在未运行服务的情况下运行客户端应用程序，则会出现此错误。