How to compare passing an object by value from an XML Web service client to an XML Web service method and passing an object by reference from an XML Web service client to an XML Web service method (833315)


The information in this article applies to:

  • Microsoft Web Services (included with the .NET Framework 1.1)
  • Microsoft Web Services (included with the .NET Framework) 1.0
  • Microsoft Visual Basic .NET (2003)
  • Microsoft Visual Basic .NET (2002)
  • Microsoft Visual Studio .NET (2003), Enterprise Architect Edition
  • Microsoft Visual Studio .NET (2003), Enterprise Developer Edition
  • Microsoft Visual Studio .NET (2003), Professional Edition
  • Microsoft Visual Studio .NET (2003), Academic Edition
  • Microsoft Visual Studio .NET (2002), Enterprise Architect Edition
  • Microsoft Visual Studio .NET (2002), Enterprise Developer Edition
  • Microsoft Visual Studio .NET (2002), Professional Edition
  • Microsoft Visual Studio .NET (2002), Academic Edition

IN THIS TASK

SUMMARY

This article compares how you can pass an object by value from an XML Web service client to an XML Web service method and how you can pass an object by reference from an XML Web service client to an XML Web service method.

Microsoft Visual Basic .NET permits you to pass an object to an XML Web service method by value or by reference. You can do this if you specify the ByVal keyword or if you specify the ByRef keyword, respectively.

Typically, when you pass an object to a method by reference, the method receives a pointer to the location of the object that is in the memory. Therefore, the method can directly make changes to the object.

However, when you pass an object to an XML Web service method, the XML Web service method receives a SOAP request that contains serialized information about the state of the object. The XML Web service method receives the SOAP request regardless of whether you pass the object by value or you pass the object by reference. For changes that the XML Web service method makes to appear in the calling code when you pass an object by reference, the XML Web service method provides a SOAP response that contains information about the new state of the object. XML Web service methods provide these SOAP responses only when you pass objects by reference. This does not occur when you pass objects by value.

Microsoft recommends that you pass an object by reference to an XML Web service method if you want the changes that the XML Web service method makes to the object to appear in the calling code.

Microsoft recommends that you pass an object by value to an XML Web service method if you want to pass data to the XML Web service method so that the changes that the XML Web service method makes to the object do not appear in the calling code.


Important If you pass an object by reference to an XML Web service method, the XML Web service method can make changes to the object. These changes may prevent your computer from functioning correctly. Therefore, Microsoft recommends that you pass an object by reference to an XML Web service method only if you trust the corresponding XML Web service.

back to the top

Create an XML Web service

To create an XML Web service that contains two XML Web service methods, follow these steps:
  1. Start Microsoft Visual Studio .NET.
  2. On the File menu, point to New, and then click Project.

    The New Project dialog box appears.
  3. Under Project Types, click Visual Basic Projects.
  4. Under Templates, click ASP.NET Web Service.
  5. In the Location box, type the following text:

    http://WebServerName/MyWebService

    Note In this step, WebServerName is a placeholder for the name of your Web server.
  6. Click OK.

    By default, the Service1.asmx file is created.
  7. In Microsoft Solution Explorer, right-click Service1.asmx, and then click View Code.
  8. In the Service1.asmx.vb file, locate the following code:
    End Class
  9. To add two XML Web service methods to the MyWebService XML Web service, add the following code before the code that you located in step 8:
    ' The MyWebServiceMethod1 XML Web service method accepts an AppDomainSetup object as an argument.
' This XML Web service method then modifies the argument.
' Because you qualify the ObjectArgument parameter with the ByVal keyword,
' the corresponding argument is passed by value.
' Therefore, any modifications to the ObjectArgument argument
' are not reflected in the calling code.
<WebMethod()> _
Public Sub MyWebServiceMethod1(ByVal ObjectArgument As AppDomainSetup)
   Dim TempObject As New AppDomainSetup
   TempObject.DisallowPublisherPolicy = False
   ' The following change is not reflected in the calling code:
   ObjectArgument = TempObject
End Sub

' The MyWebServiceMethod2 XML Web service method accepts an AppDomainSetup object as an argument.
' This XML Web service method then modifies the argument.
' Because you qualify the ObjectArgument parameter with the ByRef keyword,
' the corresponding argument is passed by reference.
' Therefore, any modifications to the ObjectArgument argument
' are also reflected in the calling code.
<WebMethod()> _
Public Sub MyWebServiceMethod2(ByRef ObjectArgument As AppDomainSetup)
   Dim TempObject As New AppDomainSetup
   TempObject.DisallowPublisherPolicy = False
   ' The following change is also reflected in the calling code:
   ObjectArgument = TempObject
End Sub
  10. On the Build menu, click Build MyWebService.
  11. On the File menu, click Close Solution.
back to the top

Configure the XML Web service to use port 8080 for all SOAP messages

To configure the MyWebService XML Web service to use port 8080 for all SOAP messages, follow these steps:
  1. Start a Visual Studio .NET command prompt.
  2. At the Visual Studio .NET command prompt, locate the Service1.asmx file that you created in step 6 of the "Create an XML Web service" section of this article.
  3. At the Visual Studio .NET command prompt, run the following command to create the Service1.wsdl file that corresponds to the MyWebService XML Web service:

    disco http://WebServerName/MyWebService/Service1.asmx



    Note In this step, WebServerName is a placeholder for the name of your Web server.
  4. Use a text editor, such as Notepad, to open the Service1.wsdl file that you created in step 3.

    Note The Service1.wsdl file exists in the same location where you created the MyWebService project in step 6 of the "Create an XML Web service" section of this article.
  5. In the Service1.wsdl file, locate the following code:
    <soap:address location="http://WebServerName/MyWebService/Service1.asmx" />
    Note In this step, WebServerName is a placeholder for the name of your Web server.
  6. To configure your XML Web service to use port 8080 for all SOAP messages, replace the code that you located in step 5 with the following code:
    <soap:address location="http://WebServerName:8080/MyWebService/Service1.asmx" />
    Note In this step, WebServerName is a placeholder for the name of your Web server.
  7. Save the Service1.wsdl file, and then exit the text editor.
back to the top

Create an XML Web service client

To create a Console application that is a client of the MyWebService XML Web service, follow these steps:
  1. Start Visual Studio .NET.
  2. On the File menu, point to New, and then click Project.

    The New Project dialog box appears.
  3. Under Project Types, click Visual Basic Projects.
  4. Under Templates, click Console Application.
  5. In the Name box, type MyWebServiceClient, and then click OK.

    By default, the Module1.vb file is created.
back to the top

Add an XML Web service reference in the XML Web service client

To add a Web reference to the MyWebService XML Web service in the XML Web service client, follow these steps:
  1. On the Project menu, click Add Web Reference.

    The Add Web Reference dialog box appears.
  2. If you are using Microsoft Visual Basic .NET 2003, type the URL of the Service1.wsdl file in the URL box, and then press the ENTER key.

    If you are using Microsoft Visual Basic .NET 2002, type the URL of the Service1.wsdl file in the Address box, and then press the ENTER key.

    For example, type the following URL to locate the Service1.wsdl file that you created in the "Configure the XML Web service to use port 8080 for all SOAP messages" section of this article:

    http://WebServerName/MyWebService/Service1.wsdl

    Note In this step, WebServerName is a placeholder for the name of your Web server.
  3. After the Microsoft .NET Framework locates the Service1.wsdl file, click Add Reference.
  4. To use the MyWebService XML Web service, add the following statement at the top of the Module1.vb file:
    Imports MyWebServiceClient.WebReferenceName
    Note In this step, WebReferenceName is a placeholder for the name of the Web reference as it appears in the Web References folder in Solution Explorer.
back to the top

Consume the XML Web service from the XML Web service client

To consume the MyWebService XML Web service from the XML Web service client, follow these steps:
  1. In the Module1.vb file, locate the following code:
    Sub Main()
  2. Add the following code after the code that you located in step 1:
    ' Create an instance of the referenced XML Web service.
Dim MyService As New Service1()
' Create an instance of the AppDomainSetup class.
Dim MyObject As New AppDomainSetup()

' Set the initial value of the DisallowPublisherPolicy property.
MyObject.DisallowPublisherPolicy = True
' Display the initial value of the DisallowPublisherPolicy property.
Console.WriteLine("The initial value of the DisallowPublisherPolicy property is " _
   + MyObject.DisallowPublisherPolicy.ToString())
Console.WriteLine("Call the MyWebServiceMethod1 Web service method.")
' Pass the MyObject object to the MyWebServiceMethod1 XML Web service method by value.
MyService.MyWebServiceMethod1(MyObject)
' Display the value of the DisallowPublisherPolicy property
' after calling the MyWebServiceMethod1 XML Web service method.
Console.WriteLine("When you pass by value, the DisallowPublisherPolicy property remains as " _
   + MyObject.DisallowPublisherPolicy.ToString())

' Set the initial value of the DisallowPublisherPolicy property.
MyObject.DisallowPublisherPolicy = True
' Display the initial value of the DisallowPublisherPolicy property.
Console.WriteLine("The initial value of the DisallowPublisherPolicy property is " _
   + MyObject.DisallowPublisherPolicy.ToString())
Console.WriteLine("Call the MyWebServiceMethod2 Web service method.")
' Pass the MyObject object to the MyWebServiceMethod2 XML Web service method by value.
MyService.MyWebServiceMethod2(MyObject)
' Display the value of the DisallowPublisherPolicy property
' after calling the MyWebServiceMethod2 XML Web service method.
Console.WriteLine("When you pass by reference, the DisallowPublisherPolicy property becomes " _
   + MyObject.DisallowPublisherPolicy.ToString())

Console.WriteLine("Press ENTER to quit.")
Console.ReadLine()
  3. On the Build menu, click Build MyWebServiceClient.
back to the top

Use the Trace Utility to view SOAP messages

To compare the SOAP request message when you pass an object by value with the SOAP response message when you pass an object by reference, use the Trace Utility. To do this, follow these steps:
  1. Run the Trace Utility.

    Note The Trace Utility is included with SOAP Toolkit 3.0. To download SOAP Toolkit 3.0, visit the following Microsoft Web site:

    http://www.microsoft.com/downloads/details.aspx?FamilyId=C943C0DD-CEEC-4088-9753-86F052EC8450&displaylang=en

  2. On the File menu, point to New, and then click Formatted Trace.

    The Trace Setup dialog box appears.
  3. In the Trace Setup dialog box, verify that the Local port # box contains 8080, and then click OK.
back to the top

Verify that your application works

To verify that your application works and to compare how you can pass an object by value and how you can pass an object by reference, follow these steps:
  1. Start Visual Studio .NET.
  2. On the Debug menu, click Start to run the XML Web service client.

    You receive the following message in the Console window:The initial value of the DisallowPublisherPolicy property is True
    Call the MyWebServiceMethod1 XML Web service method.
    When you pass by value, the DisallowPublisherPolicy property remains as True
    The initial value of the DisallowPublisherPolicy property is True
    Call the MyWebServiceMethod2 XML Web service method.
    When you pass by reference, the DisallowPublisherPolicy property becomes False
    Press ENTER to quit.
  3. Press the ENTER key to close your application.
  4. Switch to the Trace Utility.
  5. In the left pane, expand 127.0.0.1.

    Note The 127.0.0.1 value represents the Internet Protocol (IP) address that corresponds to the localhost value.
  6. In the left pane, click Message # 1.

    The upper-right pane contains the following SOAP request. This SOAP request corresponds to the SOAP request to the MyWebServiceMethod1 XML Web service method. The MyWebServiceMethod1 XML Web service method accepts an object that you pass by value. The following SOAP request contains serialized information about the state of the object that you pass by value:
    <?xml version="1.0" encoding="utf-8" ?> 
- <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
- <soap:Body>
- <MyWebServiceMethod1 xmlns="http://tempuri.org/">
- <ObjectArgument>
  <DisallowPublisherPolicy>true</DisallowPublisherPolicy> 
  <DisallowBindingRedirects>false</DisallowBindingRedirects> 
  <DisallowCodeDownload>false</DisallowCodeDownload> 
  <LoaderOptimization>NotSpecified</LoaderOptimization> 
  </ObjectArgument>
  </MyWebServiceMethod1>
  </soap:Body>
  </soap:Envelope>
    The lower-right pane contains the following SOAP response. This SOAP response corresponds to the SOAP response from the MyWebServiceMethod1 XML Web service method. The following SOAP response does not contain any information about the state of the object that you pass by value:
    <?xml version="1.0" encoding="utf-8" ?> 
- <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
- <soap:Body>
  <MyWebServiceMethod1Response xmlns="http://tempuri.org/" /> 
  </soap:Body>
  </soap:Envelope>
  7. In the left pane, click Message # 2.

    The upper-right pane contains the following SOAP request. This SOAP request corresponds to the SOAP request to the MyWebServiceMethod2 XML Web service method. The MyWebServiceMethod2 XML Web service method accepts an object that you pass by reference. This SOAP request contains serialized information about the state of the object that you pass by reference. This serialized information is the same as the serialized information that you noticed in step 6.
    <?xml version="1.0" encoding="utf-8" ?> 
- <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
- <soap:Body>
- <MyWebServiceMethod2 xmlns="http://tempuri.org/">
- <ObjectArgument>
  <DisallowPublisherPolicy>true</DisallowPublisherPolicy> 
  <DisallowBindingRedirects>false</DisallowBindingRedirects> 
  <DisallowCodeDownload>false</DisallowCodeDownload> 
  <LoaderOptimization>NotSpecified</LoaderOptimization> 
  </ObjectArgument>
  </MyWebServiceMethod2>
  </soap:Body>
  </soap:Envelope>
    The lower-right pane contains the following SOAP response. This SOAP response corresponds to the SOAP response from the MyWebServiceMethod2 XML Web service method. This SOAP response contains information about the state of the object that you pass by reference, including the new value of the DisallowPublisherPolicy property.
    <?xml version="1.0" encoding="utf-8" ?> 
- <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
- <soap:Body>
- <MyWebServiceMethod2Response xmlns="http://tempuri.org/">
- <ObjectArgument>
  <DisallowPublisherPolicy>false</DisallowPublisherPolicy> 
  <DisallowBindingRedirects>false</DisallowBindingRedirects> 
  <DisallowCodeDownload>false</DisallowCodeDownload> 
  <LoaderOptimization>NotSpecified</LoaderOptimization> 
  </ObjectArgument>
back to the top

REFERENCES

For additional information, click the following article number to view the article in the Microsoft Knowledge Base:

818364 HOW TO: Access a Web service in a Windows application by using Microsoft Visual Basic .NET

For more information about how to pass arguments by value and about how to pass arguments by reference, visit the following Microsoft Web site:

http://msdn.microsoft.com/library/en-us/vbcn7/html/vaconArgPassMechanism.asp

For more information about how to use the SOAP Trace Utility, visit the following Microsoft Web site:

http://msdn.microsoft.com/library/en-us/dnsoap/html/soap_faq.asp

back to the top
Modification Type:MajorLast Reviewed:2/6/2004
Keywords:kbToolkit kbProgramming kbConsole kbXML kbWebServices kbWebServer kbIDEProject kbCommandLine KbClientServer kbClient kbSample kbcode kbinfo KB833315 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.