Vlastní publikace WSDL

2025-06-17

System.ServiceModel.Description.IWsdlExportExtension Implementujte u vlastního System.ServiceModel.Description.IContractBehavior atributu export vlastností atributů jako poznámky WSDL.
Implementujte System.ServiceModel.Description.IWsdlImportExtension pro import vlastních poznámek WSDL.
Implementujte System.ServiceModel.Description.IServiceContractGenerationExtension a System.ServiceModel.Description.IOperationContractGenerationExtension u vlastního chování kontraktu a vlastního chování operace, v uvedeném pořadí, abyste mohli napsat importované poznámky jako komentáře v CodeDom pro importovaný kontrakt a operaci.
System.ServiceModel.Description.MetadataExchangeClient použijte ke stažení WSDL, System.ServiceModel.Description.WsdlImporter k importu WSDL pomocí vlastního importéru WSDL a System.ServiceModel.Description.ServiceContractGenerator k vygenerování klientského kódu Windows Communication Foundation (WCF) s WSDL poznámkami jako /// a ''' komentáři v jazycích C# a Visual Basic.

Poznámka:

Postup nastavení a pokyny k sestavení pro tuto ukázku najdete na konci tohoto tématu.

Služba

Služba v této ukázce je označená dvěma vlastními atributy. První, WsdlDocumentationAttribute, přijímá řetězec v konstruktoru a lze ho použít k zajištění rozhraní smlouvy nebo operace s řetězcem, který popisuje jeho použití. Druhý parametr , WsdlParamOrReturnDocumentationAttributelze použít pro vrácení hodnot nebo parametrů k popisu těchto hodnot v operaci. Následující příklad ukazuje kontrakt služby , ICalculatorpopsané pomocí těchto atributů.

// 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 implementuje IContractBehavior a IOperationBehavior, takže instance atributů jsou přidány do odpovídajících ContractDescription nebo OperationDescription při otevření služby. Atribut také implementuje IWsdlExportExtension. Je-li volána ExportContract(WsdlExporter, WsdlContractConversionContext), jsou předány jako parametry WsdlExporter, která se používá k exportu metadat, a WsdlContractConversionContext, které obsahuje objekty popisu služby, což umožňuje upravit exportovaná metadata.

V této ukázce se v závislosti na tom, zda objekt kontextu exportu má ContractDescription nebo OperationDescription, komentář extrahuje z atributu pomocí textové vlastnosti a přidá se do elementu poznámky WSDL, jak je znázorněno v následujícím kódu.

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);
        }
    }
}

Pokud se operace exportuje, použije ukázka reflexi k získání hodnot WsdlParamOrReturnDocumentationAttribute parametrů a návratových hodnot a jejich přidání do elementů poznámek WSDL pro tuto operaci následujícím způsobem.

// 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);
    }
}

Ukázka pak publikuje metadata standardním způsobem pomocí následujícího konfiguračního souboru.

<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>

Klient Svcutil

Tato ukázka nepoužívá Svcutil.exe. Kontrakt je uveden v souboru generatedClient.cs, takže po demonstraci vlastního importu WSDL a generování kódu lze službu vyvolat. Pokud chcete v tomto příkladu použít následující vlastní nástroj pro import WSDL, můžete spustit Svcutil.exe a zadat /svcutilConfig cestu ke konfiguračnímu souboru klienta použitému v této ukázce, která odkazuje na knihovnu WsdlDocumentation.dll. Aby bylo možné načíst WsdlDocumentationImporter, musí Svuctil.exe být schopen vyhledat a načíst knihovnu WsdlDocumentation.dll, což znamená, že buď je zaregistrovaná v globální mezipaměti sestav, nachází se v systému cest, nebo je ve stejném adresáři jako Svcutil.exe. V případě základní ukázky, jako je tato, je nejjednodušší zkopírovat Svcutil.exe a konfigurační soubor klienta do stejného adresáře jako WsdlDocumentation.dll a spustit ho odtud.

Vlastní importér WSDL

Vlastní objekt IWsdlImportExtensionWsdlDocumentationImporter rovněž implementuje IContractBehavior a IOperationBehavior, které mají být přidány k importovaným ServiceEndpoints, a IServiceContractGenerationExtension IOperationContractGenerationExtension, které mají být použity ke změně generování kódu při vytváření kontraktu nebo operačního kódu.

Nejprve v ImportContract(WsdlImporter, WsdlContractConversionContext) metodě ukázka určuje, zda je poznámka WSDL na úrovni kontraktu nebo operace, a přidá se jako chování v příslušném oboru a předá importovaný text poznámky jeho konstruktoru.

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));
            }
        }
    }
}

Pak, když se kód vygeneruje, systém vyvolá metody GenerateContract(ServiceContractGenerationContext) a GenerateOperation(OperationContractGenerationContext) a předá příslušné kontextové informace. Vzor formátuje vlastní anotace WSDL a vkládá je jako komentáře do 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.");
}

Klientská aplikace

Klientská aplikace načte vlastní importér WSDL tím, že ho specifikuje v konfiguračním souboru aplikace.

<client>
  <endpoint address="http://localhost/servicemodelsamples/service.svc"
  binding="wsHttpBinding"
  contract="ICalculator" />
  <metadata>
    <wsdlImporters>
      <extension type="Microsoft.ServiceModel.Samples.WsdlDocumentationImporter, WsdlDocumentation"/>
    </wsdlImporters>
  </metadata>
</client>

Jakmile je zadán vlastní import, systém metadat WCF načte vlastní import do jakéhokoli WsdlImporter vytvořeného pro tento účel. Tato ukázka používá MetadataExchangeClient ke stažení metadat, správně nakonfigurovaného pro import metadat pomocí vlastního importu, který ukázka vytvoří, a WsdlImporter ke kompilaci upravených informací o kontraktu do klientského kódu jazyka Visual Basic i C#, ServiceContractGenerator který lze použít v sadě Visual Studio k podpoře IntelliSense nebo zkompilování do dokumentace 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);
}

Jak nastavit, sestavit a spustit ukázku

Ujistěte se, že jste provedli instalační proceduru One-Time pro ukázky Windows Communication Foundation.
Pokud chcete sestavit verzi C# nebo Visual Basic .NET řešení, postupujte podle pokynů v Sestavení ukázek Windows Communication Foundation.
Pokud chcete spustit ukázku v konfiguraci pro jeden počítač nebo pro více počítačů, postupujte podle pokynů v Spuštění ukázek Windows Communication Foundation.

Sdílet prostřednictvím