WsdlDocumentation 範例示範如何：
在自訂System.ServiceModel.Description.IWsdlExportExtension屬性上實施System.ServiceModel.Description.IContractBehavior，將屬性匯出為 WSDL 註釋。
實現System.ServiceModel.Description.IWsdlImportExtension以匯入自定義 WSDL 註釋。
在自定義合約行為和自定義作業行為上實作System.ServiceModel.Description.IServiceContractGenerationExtension和System.ServiceModel.Description.IOperationContractGenerationExtension，以將匯入的批註撰寫為匯入合約和作業之CodeDom中的註解。
System.ServiceModel.Description.MetadataExchangeClient用來下載 WSDL，System.ServiceModel.Description.WsdlImporter用來使用自定義 WSDL 匯入工具匯入 WSDL，System.ServiceModel.Description.ServiceContractGenerator用來產生具有 WSDL 註釋的 Windows Communication Foundation （WCF）用戶端代碼，將註釋作為 C# 和 Visual Basic 中的 /// 和 ''' 註解。
備註
此範例的安裝程式和建置指示位於本主題結尾。
服務
此範例中的服務會以兩個自定義屬性標示。 第一個是 WsdlDocumentationAttribute，接受建構子中的字串，並且可以利用描述其用法的字串來提供契約介面或作業。 第二個 ， WsdlParamOrReturnDocumentationAttribute可以套用至傳回值或參數，以描述作業中的這些值。 下列範例示範使用這些屬性描述的服務合約 ICalculator。
// Define a service contract.
[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]
// Document it.
[WsdlDocumentation("The ICalculator contract performs basic calculation services.")]
public interface ICalculator
{
[OperationContract]
[WsdlDocumentation("The Add operation adds two numbers and returns the result.")]
[return:WsdlParamOrReturnDocumentation("The result of adding the two arguments together.")]
double Add(
[WsdlParamOrReturnDocumentation("The first value to add.")]double n1,
[WsdlParamOrReturnDocumentation("The second value to add.")]double n2
);
[OperationContract]
[WsdlDocumentation("The Subtract operation subtracts the second argument from the first.")]
[return:WsdlParamOrReturnDocumentation("The result of the second argument subtracted from the first.")]
double Subtract(
[WsdlParamOrReturnDocumentation("The value from which the second is subtracted.")]double n1,
[WsdlParamOrReturnDocumentation("The value that is subtracted from the first.")]double n2
);
[OperationContract]
[WsdlDocumentation("The Multiply operation multiplies two values.")]
[return:WsdlParamOrReturnDocumentation("The result of multiplying the first and second arguments.")]
double Multiply(
[WsdlParamOrReturnDocumentation("The first value to multiply.")]double n1,
[WsdlParamOrReturnDocumentation("The second value to multiply.")]double n2
);
[OperationContract]
[WsdlDocumentation("The Divide operation returns the value of the first argument divided by the second argument.")]
[return:WsdlParamOrReturnDocumentation("The result of dividing the first argument by the second.")]
double Divide(
[WsdlParamOrReturnDocumentation("The numerator.")]double n1,
[WsdlParamOrReturnDocumentation("The denominator.")]double n2
);
}
WsdlDocumentationAttribute 實作 IContractBehavior 和 IOperationBehavior，因此，開啟服務時，屬性實例會加入對應的 ContractDescription 或 OperationDescription。 屬性也會實作 IWsdlExportExtension。 當呼叫ExportContract(WsdlExporter, WsdlContractConversionContext)時，會將用來匯出元數據的WsdlExporter和包含服務描述物件的WsdlContractConversionContext，作為參數傳入，以啟用對匯出元數據的修改。
在此範例中，根據匯出內容物件是否具有 ContractDescription 或 OperationDescription 而定，會使用 text 欄位從屬性中提取批註，並將其新增至 WSDL 註釋元素，如下列程式碼所示。
public void ExportContract(WsdlExporter exporter, WsdlContractConversionContext context)
{
if (contractDescription != null)
{
// Inside this block it is the contract-level comment attribute.
// This.Text returns the string for the contract attribute.
// Set the doc element; if this isn't done first, there is no XmlElement in the
// DocumentElement property.
context.WsdlPortType.Documentation = string.Empty;
// Contract comments.
XmlDocument owner = context.WsdlPortType.DocumentationElement.OwnerDocument;
XmlElement summaryElement = owner.CreateElement("summary");
summaryElement.InnerText = this.Text;
context.WsdlPortType.DocumentationElement.AppendChild(summaryElement);
}
else
{
Operation operation = context.GetOperation(operationDescription);
if (operation != null)
{
// We are dealing strictly with the operation here.
// This.Text returns the string for the operation-level attributes.
// Set the doc element; if this isn't done first, there is no XmlElement in the
// DocumentElement property.
operation.Documentation = String.Empty;
// Operation C# triple comments.
XmlDocument owner = operation.DocumentationElement.OwnerDocument;
XmlElement newSummaryElement = owner.CreateElement("summary");
newSummaryElement.InnerText = this.Text;
operation.DocumentationElement.AppendChild(newSummaryElement);
}
}
}
如果要匯出作業，此範例會使用反映來取得參數的任何 WsdlParamOrReturnDocumentationAttribute 值，並傳回值，並將其新增至該作業的 WSDL 註釋元素，如下所示。
// Get returns information
ParameterInfo returnValue = operationDescription.SyncMethod.ReturnParameter;
object[] returnAttrs = returnValue.GetCustomAttributes(typeof(WsdlParamOrReturnDocumentationAttribute), false);
if (returnAttrs.Length != 0)
{
// <returns>text.</returns>
XmlElement returnsElement = owner.CreateElement("returns");
returnsElement.InnerText = ((WsdlParamOrReturnDocumentationAttribute)returnAttrs[0]).ParamComment;
operation.DocumentationElement.AppendChild(returnsElement);
}
// Get parameter information.
ParameterInfo[] args = operationDescription.SyncMethod.GetParameters();
for (int i = 0; i < args.Length; i++)
{
object[] docAttrs = args[i].GetCustomAttributes(typeof(WsdlParamOrReturnDocumentationAttribute), false);
if (docAttrs.Length == 1)
{
// <param name="Int1">Text.</param>
XmlElement newParamElement = owner.CreateElement("param");
XmlAttribute paramName = owner.CreateAttribute("name");
paramName.Value = args[i].Name;
newParamElement.InnerText = ((WsdlParamOrReturnDocumentationAttribute)docAttrs[0]).ParamComment;
newParamElement.Attributes.Append(paramName);
operation.DocumentationElement.AppendChild(newParamElement);
}
}
然後範例會使用下列組態檔，以標準方式發佈元數據。
<services>
<service
name="Microsoft.ServiceModel.Samples.CalculatorService"
behaviorConfiguration="CalculatorServiceBehavior">
<!-- ICalculator is exposed at the base address provided by host: http://localhost/servicemodelsamples/service.svc -->
<endpoint address=""
binding="wsHttpBinding"
contract="Microsoft.ServiceModel.Samples.ICalculator" />
<!-- the mex endpoint is exposed at http://localhost/servicemodelsamples/service.svc/mex -->
<endpoint address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange" />
</service>
</services>
<!--For debugging purposes set the includeExceptionDetailInFaults attribute to true-->
<behaviors>
<serviceBehaviors>
<behavior name="CalculatorServiceBehavior">
<serviceMetadata httpGetEnabled="True"/>
<serviceDebug includeExceptionDetailInFaults="False" />
</behavior>
</serviceBehaviors>
</behaviors>
Svcutil 用戶端
這個範例不會使用 Svcutil.exe。 合約會在 generatedClient.cs 檔案中提供，如此一來，在範例示範自定義WSDL 匯入和程式代碼產生之後，就可以叫用服務。 若要針對此範例使用下列自定義 WSDL 匯入工具，您可以執行 Svcutil.exe 並指定 /svcutilConfig 選項，並提供此範例中使用的用戶端組態檔路徑，以參考 WsdlDocumentation.dll 連結庫。 不過，若要載入 WsdlDocumentationImporter，Svuctil.exe 必須能夠找出並載入 WsdlDocumentation.dll 連結庫，這表示它已註冊於全域程式集緩存、路徑中，或位於與 Svcutil.exe相同的目錄中。 對於這類基本範例，最簡單的方法是將 Svcutil.exe 和用戶端組態檔複製到相同的目錄中 WsdlDocumentation.dll ，然後從該處執行。
自訂 WSDL 匯入工具
自定義IWsdlImportExtension物件WsdlDocumentationImporter還將實作IContractBehavior並IOperationBehavior將其新增至匯入的ServiceEndpoints中，並在合約或作業程式代碼建立時叫用IServiceContractGenerationExtension與IOperationContractGenerationExtension來修改程式碼生成。
首先，在 ImportContract(WsdlImporter, WsdlContractConversionContext) 方法中，此範例會判斷 WSDL 註釋是位於合約層級還是作業層級，並將自身新增為適當範圍的行為，並將匯入的註釋文字傳遞至其建構函式。
public void ImportContract(WsdlImporter importer, WsdlContractConversionContext context)
{
// Contract Documentation
if (context.WsdlPortType.Documentation != null)
{
// System examines the contract behaviors to see whether any implement IWsdlImportExtension.
context.Contract.Behaviors.Add(new WsdlDocumentationImporter(context.WsdlPortType.Documentation));
}
// Operation Documentation
foreach (Operation operation in context.WsdlPortType.Operations)
{
if (operation.Documentation != null)
{
OperationDescription operationDescription = context.Contract.Operations.Find(operation.Name);
if (operationDescription != null)
{
// System examines the operation behaviors to see whether any implement IWsdlImportExtension.
operationDescription.Behaviors.Add(new WsdlDocumentationImporter(operation.Documentation));
}
}
}
}
然後，當程式代碼產生時，系統會調用 GenerateContract(ServiceContractGenerationContext) 和 GenerateOperation(OperationContractGenerationContext) 方法，並傳遞適當的上下文資訊。 範例會格式化自定義 WSDL 批注，並將其插入 CodeDom 中做為批注。
public void GenerateContract(ServiceContractGenerationContext context)
{
Debug.WriteLine("In generate contract.");
context.ContractType.Comments.AddRange(FormatComments(text));
}
public void GenerateOperation(OperationContractGenerationContext context)
{
context.SyncMethod.Comments.AddRange(FormatComments(text));
Debug.WriteLine("In generate operation.");
}
用戶端應用程式
用戶端應用程式會在應用程式組態檔中指定自訂 WSDL 匯入工具，以載入該工具。
<client>
<endpoint address="http://localhost/servicemodelsamples/service.svc"
binding="wsHttpBinding"
contract="ICalculator" />
<metadata>
<wsdlImporters>
<extension type="Microsoft.ServiceModel.Samples.WsdlDocumentationImporter, WsdlDocumentation"/>
</wsdlImporters>
</metadata>
</client>
指定自定義匯入工具之後，WCF 元數據系統會將自定義匯入工具載入至任何專為此目的而建立的 WsdlImporter。 此範例會使用 MetadataExchangeClient 下載元數據、 WsdlImporter 正確設定為使用範例建立的自定義匯入工具匯入元數據，以及 ServiceContractGenerator 將修改過的合約資訊編譯成 Visual Basic 和 C# 用戶端程式代碼，這些程式代碼可用於 Visual Studio 以支援 Intellisense 或編譯成 XML 檔。
/// From WSDL Documentation:
///
/// <summary>The ICalculator contract performs basic calculation
/// services.</summary>
///
[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]
[System.ServiceModel.ServiceContractAttribute(Namespace="http://Microsoft.ServiceModel.Samples", ConfigurationName="ICalculator")]
public interface ICalculator
{
/// From WSDL Documentation:
///
/// <summary>The Add operation adds two numbers and returns the
/// result.</summary><returns>The result of adding the two arguments
/// together.</returns><param name="n1">The first value to add.</param><param
/// name="n2">The second value to add.</param>
///
[System.ServiceModel.OperationContractAttribute(Action="http://Microsoft.ServiceModel.Samples/ICalculator/Add", ReplyAction="http://Microsoft.ServiceModel.Samples/ICalculator/AddResponse")]
double Add(double n1, double n2);
/// From WSDL Documentation:
///
/// <summary>The Subtract operation subtracts the second argument from the
/// first.</summary><returns>The result of the second argument subtracted from the
/// first.</returns><param name="n1">The value from which the second is
/// subtracted.</param><param name="n2">The value that is subtracted from the
/// first.</param>
///
[System.ServiceModel.OperationContractAttribute(Action="http://Microsoft.ServiceModel.Samples/ICalculator/Subtract", ReplyAction="http://Microsoft.ServiceModel.Samples/ICalculator/SubtractResponse")]
double Subtract(double n1, double n2);
/// From WSDL Documentation:
///
/// <summary>The Multiply operation multiplies two values.</summary><returns>The
/// result of multiplying the first and second arguments.</returns><param
/// name="n1">The first value to multiply.</param><param name="n2">The second value
/// to multiply.</param>
///
[System.ServiceModel.OperationContractAttribute(Action="http://Microsoft.ServiceModel.Samples/ICalculator/Multiply", ReplyAction="http://Microsoft.ServiceModel.Samples/ICalculator/MultiplyResponse")]
double Multiply(double n1, double n2);
/// From WSDL Documentation:
///
/// <summary>The Divide operation returns the value of the first argument divided
/// by the second argument.</summary><returns>The result of dividing the first
/// argument by the second.</returns><param name="n1">The numerator.</param><param
/// name="n2">The denominator.</param>
///
[System.ServiceModel.OperationContractAttribute(Action="http://Microsoft.ServiceModel.Samples/ICalculator/Divide", ReplyAction="http://Microsoft.ServiceModel.Samples/ICalculator/DivideResponse")]
double Divide(double n1, double n2);
}