Crear un proxy de servicio Web XML

Por definición, se puede comunicar con los servicios Web XML a través de una red mediante protocolos estándar, incluido el protocolo SOAP. Esto significa que un cliente y un servicio Web XML se comunican mediante mensajes SOAP, que encapsulan los parámetros in y out como XML. Afortunadamente, para los clientes de servicios Web XML, la clase de proxy controla el trabajo de asignar parámetros a elementos XML y, después, enviar el mensaje SOAP a través de la red.

Siempre que exista una descripción de servicio, se puede generar una clase de proxy si la descripción de servicio es compatible con WSDL (Lenguaje de descripción de servicios Web). En una descripción de servicio se define la manera de comunicarse con un servicio Web XML. Con una descripción de servicio, se puede crear una clase de proxy mediante la herramienta Wsdl.exe. A su vez, un cliente de servicios Web XML puede llamar a métodos de la clase de proxy que se comunican con un servicio a través de la red mediante el procesamiento de los mensajes SOAP enviados y recibidos por el servicio Web XML. Como la clase de proxy se comunica con el servicio Web XML a través de Internet, es una buena idea comprobar que la propiedad Url de la clase de proxy hace referencia a un destino de confianza.

De forma predeterminada, la clase de proxy utiliza SOAP sobre HTTP para comunicarse con el servicio Web XML. Sin embargo, Wsdl.exe puede generar clases de proxy para comunicarse con un servicio Web XML mediante el protocolo HTTP-GET o el protocolo HTTP-POST. Para especificar que la clase de proxy debe utilizar HTTP-GET o HTTP-POST, proporcione el modificador /protocol a la herramienta Wsdl.exe, como se describe en la tabla siguiente.

Para generar una clase de proxy de servicio Web XML

• En el símbolo del sistema, utilice la herramienta Wsdl.exe para crear una clase de proxy en la que se especifique, como mínimo, la dirección URL de un servicio Web XML o de una descripción de servicio, o la ruta de acceso de una descripción de servicio guardada.

  Wsdl /language:language  /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>
  

  Nota: los argumentos enumerados anteriormente son los que se utilizan habitualmente para la herramienta Wsdl.exe. Para obtener la sintaxis completa de la herramienta Wsdl.exe, vea la ** herramienta Lenguaje de descripción de servicios Web (Wsdl.exe).

  Parámetro	Valor
  <url or path>	Dirección URL o ruta de acceso de una descripción de servicio (un archivo en el que se describe un servicio Web XML en WSDL). Si especifica un archivo, proporcione uno que contenga la descripción de servicio. Por ejemplo: mywebservice.wsdl Si especifica una dirección URL, ésta debe hacer referencia a una página .asmx o devolver una descripción de servicio. Para los servicios Web XML creados mediante ASP.NET, puede devolver una descripción de servicio si agrega ?WSDL al final de la dirección URL del servicio Web XML. Por ejemplo, https://www.contoso.com/MyWebService.asmx?WSDL
  /language:language	Lenguaje en el que se genera la clase de proxy. Entre las opciones disponibles se incluyen CS, VB y JS, que hacen referencia a C#, Visual Basic .NET y JScript .NET, respectivamente. El lenguaje predeterminado es C#. (Opcional)
  /protocol:protocol	Protocolo utilizado para la comunicación con los métodos de servicio Web XML. Entre las opciones disponibles se incluyen SOAP, HTTP-GET y HTTP-POST. El protocolo predeterminado es SOAP. (Opcional)
  /namespace:myNameSpace	Espacio de nombres del proxy generado. El valor predeterminado es el espacio de nombres global. (Opcional)
  /out:filename	Nombre del archivo que se creará con la clase de proxy. El nombre predeterminado se basa en el nombre de la clase que implementa el servicio Web XML. (Opcional)
  /username:username	Nombre de usuario que se utilizará al conectar con un servidor Web que requiera autenticación. (Opcional)
  /password:password	Contraseña que se utilizará al conectar con un servidor Web que requiera autenticación. (Opcional)
  /domain:domain	Dominio que se utilizará al conectar con un servidor Web que requiera autenticación. (Opcional)

Detalles de la clase de proxy generada

Cuando se utiliza la herramienta Wsdl.exe para generar una clase de proxy, se genera un único archivo de código fuente en el lenguaje especificado. Este archivo contiene una clase de proxy que expone métodos sincrónicos y asincrónicos para cada método del servicio Web XML. Por ejemplo, si un servicio Web XML contiene un método de servicio Web XML denominado Add, la clase de proxy puede llamar al método Add con los métodos siguientes: Add, BeginAdd y EndAdd. El método Add de la clase de proxy se utiliza para comunicarse de forma sincrónica con el método de servicio Web XML Add, pero los métodos BeginAdd y EndAdd se utilizan para comunicarse de forma asincrónica con un método de servicio Web XML. Para obtener más información sobre cómo comunicarse de forma asincrónica con métodos de servicio Web XML, vea Comunicar con servicios Web XML de forma asincrónica.

Cada método de la clase de proxy generada contiene el código correspondiente para comunicarse con el método de servicio Web XML. Si se produce un error durante la comunicación con el servicio Web XML y la clase de proxy, se iniciará una excepción. Para obtener más información sobre cómo tratar las excepciones, vea Controlar e iniciar excepciones en servicios Web XML.

El orden definido de los parámetros puede ser diferente en el método de servicio Web XML y en el método asociado de la clase de proxy. En la mayoría de los casos, el orden de los parámetros coincidirá. Sin embargo, si el servicio Web XML espera recibir mensajes SOAP con formato Document, hay un caso en el que el orden de los parámetros no coincidirá. Si un método de servicio Web XML tiene definidos parámetros out delante de un parámetro in, los parámetros out se colocan al final de todos los parámetros in en la clase de proxy. En el ejemplo de código siguiente, el método de servicio Web XML MyWebMethod tiene declarado el parámetro out outStr antes que el parámetro in inStr. Sin embargo, en la clase de proxy, el parámetro inStr se declara antes que outStr.

En algunos casos, la clase de proxy generada por WSDL.exe utiliza un enfoque de nivel más bajo para convertir los objetos a un tipo especificado en una descripción de servicio. Como consecuencia, es posible que el tipo generado en la clase de proxy no sea el que desea o espera el programador. Por ejemplo, cuando WSDL.exe encuentra un tipo ArrayList en una descripción de servicio, crea una matriz de objetos en la clase de proxy generada. Para garantizar que las conversiones de tipo de objeto sean correctas, abra el archivo que contiene la clase de proxy generada y cambie los tipos de objeto incorrectos al tipo de objeto esperado.

' Declare MyWebMethod in the XML Web service.
MyWebMethod(ByRef outStr As String, inStr As String)

' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)
[C#]
// Declare MyWebMethod in the XML Web service.
MyWebMethod(out string outStr, string inStr)

// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).

En algunos casos, la clase de proxy generada por WSDL.exe utiliza un enfoque de nivel más bajo para convertir los objetos a un tipo especificado en una descripción de servicio. Como consecuencia, es posible que el tipo generado en la clase de proxy no sea el que desea o espera el programador. Por ejemplo, cuando WSDL.exe encuentra un tipo ArrayList en una descripción de servicio, crea una matriz Object en la clase de proxy generada. Para garantizar que las conversiones de tipo de objeto sean correctas, abra el archivo que contiene la clase de proxy generada y cambie los tipos de objeto incorrectos al tipo de objeto esperado.

Advertencias emitidas por Wsdl.exe

Al suministrar varias descripciones de servicio a la herramienta Wsdl.exe, dos de los mensajes de error que se pueden producir son similares a los siguientes:

• Advertencia: se omitirán las descripciones de servicio duplicadas con TargetNamespace=<espacio de nombres del esquema> de la ubicación <URI del esquema>.

  Indica que el elemento TargetNamespace es idéntico en dos o más de las descripciones de servicio suministradas. Como se supone que TargetNamespace es un identificador único de un documento XML determinado, que es una descripción de servicio en este caso, la herramienta Wsdl.exe supone que las dos descripciones de servicio son idénticas. En consecuencia, Wsdl.exe sólo crea una clase de proxy para una de las descripciones. Si éste no es el resultado previsto, se puede cambiar. Para las descripciones de servicio que representen servicios Web XML creados mediante ASP.NET, puede aplicar un atributo WebService en el que se especifique una propiedad Namespace única para la clase que implementa el servicio Web XML. Después, la propiedad Namespace se utilizará como TargetNamespace, en la descripción de servicio, para identificar de forma única el servicio Web XML. Para obtener más información sobre cómo establecer la propiedad Namespace, vea Aplicar un atributo WebService.

• Advertencia: se omitirán los esquemas duplicados con TargetNamespace=<espacio de nombres del esquema> de la ubicación <URI del esquema>.

  Indica que el elemento TargetNamespace es idéntico en dos o más esquemas XML en las descripciones de servicio suministradas. Como se supone que TargetNamespace es un identificador único de un documento XML determinado, que es el esquema XML en este caso, Wsdl.exe supone que los dos esquemas XML son idénticos. En consecuencia, Wsdl.exe sólo crea una clase para uno de los esquemas. Si éste no es el resultado previsto, el elemento TargetNamespace de cada esquema XML se debe cambiar a un URI único. La forma exacta de modificar el elemento TargetNamespace depende del origen de los esquemas XML específicos.

Vea también

Generar clientes de servicios Web XML | Descubrir servicios Web XML | Crear clientes para servicios Web XML | Explorar servicios Web XML existentes creados mediante ASP.NET | Comunicar con servicios Web XML de forma asincrónica | Acceso a servicios Web XML desde un explorador