Add Web Reference Dialog Box

Article
11/16/2012

The Add Web Reference dialog box enables you to browse for Web services and add Web references to a Web site. A Web reference enables you to use objects and methods provided by a Web service in your code. You can search for Web services on a local computer or on servers in your company's local area network, or you can search the Internet for commercial Web services.

To open the Add Web Reference dialog box

In Solution Explorer, right-click the name of the Web site and then click Add Web Reference.

The Add Web Reference dialog box appears.

After adding a Web reference to your current project, you can use any element or functionality provided by that Web service in your application. For more information, see XML Web Services Overview.

Security Note:
When you open a project for editing that includes a Web reference, a local proxy file for the Web service runs in an instance of the Devenv.exe process that has been started by a trusted user — yourself. Opening projects or components in the integrated development environment (IDE) can potentially enable code to be executed on the local computer. For more information, see Code Access Security.

UI Elements

Back

Returns to the previous page that was displayed.
Forward

Returns to the page that was visible when you previously clicked the Back button.
Stop

Stops loading the Web page.
Refresh

Refreshes the contents of the active page in the left browser pane.
Home

Displays the Start Browsing for Web Services page in the left browser pane.
Go

Activates a search for Web services at the address entered in the URL field.
URL
Displays the URL for a Web service that you want your application to consume. Use the drop-down list to select a service that you previously used, or enter a new path, starting with http:// or ftp://. A complete Web reference URL includes a domain name, a Web service name, and the name of its .asmx, .wsdl, .disco, or .xsd discovery file. For example, you might enter the following:

http://DomainName/WebServiceName/DiscoveryFile.asmx

The Start Browsing for Web Services pane searches this path for Web services and displays descriptions for any services found.

Note

The .NET Framework does not auto-detect proxy servers. If you are developing a Web application on a computer that is behind a firewall and your application will consume Web services found outside 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. Additionally, you can set the <defaultProxy> Element (Network Settings) element of the Machine.config or Web.config file. Any HttpWebRequest that does not include a Proxy property set to a specific value uses the default proxy. For more information, see Configuring Internet Applications.
Start Browsing for Web Services
Provides links to lists of available Web services. After clicking one of the links, you can select the name of any available Web service that is listed to retrieve descriptions of its supported methods from the Web Services Description Language (WSDL) file for the service. For more information, see Locating Web Services and WSDL File Generation for ASP.NET Web Services.

The following links are included in this pane:
- Web services in this solution Lists Web services that are available in the current solution.
- Web services on the local machine Lists Web services and discovery documents available on the local computer.
  
  For this link to return information, a Web server, such as Internet Information Services (IIS), must be running on the local computer. For more information about IIS, see the IIS Technical Library.
- Browse UDDI Servers on the local network Lists servers available in your local area network that provide Web services and discovery documents using the Universal Description, Discovery, and Integration (UDDI) protocols.
  
  Standard UDDI protocols enable quick and programmatic discovery of a company's available Web services. For more information, see the Microsoft UDDI Web site.
Web services found at this URL
Lists the names of any Web services found at the specified URL. When you create a Web reference, it will refer to this whole list. To isolate a single Web service, pause the mouse pointer over the desired item in this list. A tool tip will show the URL of the desired service. Enter the URL for that service and press Go. The list should then display only the desired Web service. You can then add a reference to just that service.
Web reference name
Specifies a unique name that you will use in your code to access the selected Web service programmatically. If the name entered matches an existing Web service, a number is appended that makes the new reference unique.

By default, Web references are assigned a namespace that corresponds to their server name. Visual Web Developer creates a Web reference based on the Web reference name that you enter in the App_WebReferences folder. Inside the App_WebReferences folder a .wsdl file that references the Web service is created, together with supporting files — such as discovery (.disco and .discomap) files — that include information about where the Web service is located.

Web reference names cannot:
- Contain any one of the following characters: / ? : \ * " < > or |
- Contain Unicode control characters.
- Be reserved names. This includes "CON", "AUX", "PRN", "COM1" and "LPT2".
Add Reference
Creates a new Web reference in your application. This button is enabled when one or more Web services available at the address entered in the URL field are listed in the Web services found at this URL field. A new Web reference with the name given in the Web reference name field will appear in Solution Explorer under the Web References node for the current project. This new Web reference will make all the Web services listed available to your application.

Note

To regenerate the proxy class for a Web service by using the latest copy of its .wsdl description file, right-click the Web reference in Solution Explorer and click Update Web Reference.