Adding and Removing Web References

Article
10/12/2006

A Web reference enables a project to consume one or more XML Web services. Use the Add Web Reference Dialog Box to search for Web services that are installed on your local machine or stored on servers within your company's local area network, or to search an Internet registry for companies that provide commercial Web services.

After adding a Web Reference to your current project, you can use any methods provided by the indicated Web service within your application. See the code snippet included in this topic for a sample Visual Basic .NET function that calls a method of a Web service.

Common Procedures

To add a Web reference to a project

In Solution Explorer, select the project that will consume the Web service.
On the Project menu, choose Add Web Reference.

The Add Web Reference dialog box opens.
Select a link in the Web browser pane on the left to search for Web services installed on your local machine, or available on servers within your company's local area network, or available from providers of commercial Web services listed in the Microsoft UDDI Business Registry.

**Note **The directory in which a XML Web service can be found will vary, depending upon the Web site you are browsing. You can also enter the complete path to a Web service in the URL field.

Select a Web service from the Services listed in the Web browser pane on the left.

The path to the selected Web service appears in the URL field. The Start Browsing for Web Services pane will search this path for Web services and display descriptions for any services found.

Note If you are developing a Web application on a machine that is behind a firewall, and your application will consume Web services found outside of the firewall, you must include the address and port of your network's proxy server in the URL. Ask your network administrator to furnish this part of the URL path. For more information, see The proxy settings on this computer are not configured correctly for Web discovery..

A simplified URL for a commercial Web service that provides a parts catalog published by a company called "ADatum" might look like this:

https://www.adatum.com/ourlist/adcatalog.asmx

URL Element	Description
www.adatum.com	The domain in which the XML Web service is deployed.
ourlist	The name of the folder containing the XML Web service. In some cases, this corresponds to the project name of the Web service.
adcatalog.asmx	The name of the discovery file for the desired XML Web service. This can be an .asmx, .wsdl, .disco, or .xsd file.

A description of the elements and methods provided by the selected Web service appears in the Browser pane on the left.

Note For more information on the items associated with an XML Web service, see XML Web Services Publishing and Deployment.

Verify that your project can use the Web service, and that any external code provided is trustworthy.

**Security Note **When you open a project for editing that includes a Web reference, a local proxy file for the Web service consumed runs in a process of devenv.exe started by a trusted user, yourself. Opening projects or components in the integrated development environment (IDE) can execute code on your local machine. For more information, see Web Application Security at Design Time in Visual Studio and Code Access Security.
In the Web reference name field, enter a name that you will use in your code to access the selected Web service programmatically.
Select the Add Reference button to create a reference in your application to the selected Web service. The new reference will appear in Solution Explorer under the Web References node for the active project, named as specified in the Web reference name field.
In Solution Explorer, expand the Web References folder to note the namespace for the Web reference classes that are available to the items in your project.

After adding a Web reference to your project, the associated files are displayed in a folder within the Web References folder of Solution Explorer.

To refresh a Web reference

Right-click on the Web reference in Solution Explorer and select Update Web Reference from its shortcut menu.

This will regenerate the proxy class for the Web service, using the latest copy of its .WSDL description file. Any methods listed in the refreshed proxy should be available from the current version of the Web service.

To remove a Web reference from a project

If your project no longer needs a Web reference to an XML Web service, you can remove the reference from your project.

In Solution Explorer, select the Web reference you want to delete.
On the Edit menu, choose Delete.

All of the reference information is removed from the project and from local storage.

Code Snippet

The following snippet of Visual Basic .NET code calls a Web service method to define a string value. Key variable names and syntax are highlighted.

To call a Web service programmatically

Use the Web reference name as the namespace, and the name of its .WSDL file as the proxy class.

' Visual Basic
   Private Sub Call_Web_Service_Method() 
         'Create an object that calls the name for the 
         'Web service used in the added Web Reference. 
      Dim CallWebService as New ServerName.WebServiceName() 
         '(Substitute the names of your own Server and Web 
         ' service for ServerName.WebServiceName above.) 
  
         'Use this object to run a method of the Web service. 
         'Save the value returned in a typed variable. 
      Dim sGetValue as String = CallWebService.MethodName() 
  
         'Set a property within your project 
         'to the value stored in this variable. 
      Label1.Text = sGetValue 
   End Sub

For more information and examples of programming with XML Web services, see Programming the Web with XML Web Services.

Adding and Removing Web References

Common Procedures

Code Snippet

See Also

Additional resources