Attaching a Web Reference

Visual Studio .NET has a special name for the machinery that hooks up a Web Service client to the server—Web reference. A Web reference consists of the WSDL (Web Services Description Language) and any related disco files. It also includes the automatically generated code that the client uses to call the Web Service. We call this generated code the proxy.

When we hook up a Web Service, we can do so two ways—through command-line tools or through the Visual Studio IDE. In this text, we will concentrate on using the Visual Studio IDE. If you want to use the command-line tool WSDL.EXE, please refer to the Framework SDK documentation.

So that you can follow along with these instructions, create a simple Visual Basic application in the Visual Studio IDE. The application type does not matter much, but to keep things simple, I recommend creating a Console Application. Let's attach to the Chapter1 Web Service using the IDE by following these steps:

At this point, the Web reference has been added to the project and is contained in the localhost namespace. . When the IDE creates the proxy, the IDE automatically places the proxy in a separate namespace. The namespace comes from the start of the URL that helped grab the namespace in the first place. If you do not like the IDE chosen namespace, you can easily change the namespace. Just go to the Solution Explorer pane within the IDE, navigate to the Web references node, and right-click the Web reference you want to change. In our case, we right-click on the node underneath the Web Reference named localhost and select Rename from the pop-up menu (see Figure 2.3). Rename localhost to something slightly more meaningful: Chapter1.

Now that this has been completed, we can also look at doing some other interesting things. In Chapter 1, “Create Your First Web Service,” I indicated that the application configuration file would be something with which you should get very familiar. We are going to continue our education by looking at how we can get our Web Service to read the endpoint URL from the configuration file.

In the IDE, go to the Solution Explorer pane and click the Chapter1 node underneath the Web References node. In the Properties pane, you should see the list of properties for the Web reference (see Figure 2.4). One of the properties is URL Behavior. This item can be static or dynamic. Static behavior means that the URL never changes and is stored in the proxy object base on the endpoint listed in the WSDL file. If the endpoint changes and you want to avoid rebuilding the application every time the Web Service does move, you can tell the application to look for the endpoint URL in the application configuration file by setting the URL Behavior to Dynamic. Under the covers, what is happening?

To answer that question, we need to look at the proxy that the IDE generates for us. That proxy is located in a subdirectory of the main project. On my machine, this is located in My DocumentsVisual Studio ProjectsChapter2CLIWeb ReferencesChapter1FirstService.vb. When the URL Behavior property is set to Static, the constructor of the proxy looks like the following:

<System.Diagnostics.DebuggerStepThroughAttribute()> _
Public Sub New()
    MyBase.New()
    Me.Url = "http://localhost/Chapter1/FirstService.asmx"
End Sub

When the URL Behavior property is set to Dynamic, the constructor of the proxy changes to the code shown in Listing 2.1.

Listing 2.1. Proxy Constructor with URL Behavior Set to Dynamic

<System.Diagnostics.DebuggerStepThroughAttribute()> _
Public Sub New()
    MyBase.New()
    Dim urlSetting As String = _
        System.Configuration.ConfigurationSettings.AppSettings( _
            "Chapter2CLI.Chapter1.FirstService")
    If (Not (urlSetting) Is Nothing) Then
        Me.Url = String.Concat(urlSetting, "")
    Else
        Me.Url = "http://localhost/Chapter1/FirstService.asmx"
    End If
End Sub
					

As you can see, the code for the Dynamic URL behavior is a little different. The Dynamic lookup still defaults to the URL listed in the WSDL file. For reference, Listing 2.2 shows the service section of the FirstService.asmx?WSDL file.

Listing 2.2. Service declaration From the FirstService.asmx?WSDL Listing

<service name="FirstService">
  <port name="FirstServiceSoap" binding="s0:FirstServiceSoap">
    <soap:address location="http://localhost/Chapter1/FirstService.asmx" />
  </port>
  <port name="FirstServiceHttpGet" binding="s0:FirstServiceHttpGet">
    <http:address location="http://localhost/Chapter1/FirstService.asmx" />
  </port>
  <port name="FirstServiceHttpPost" binding="s0:FirstServiceHttpPost">
    <http:address location="http://localhost/Chapter1/FirstService.asmx" />
  </port>
</service>

The proxy is a SOAP proxy, so it references the port named FirstServiceSoap and getting the endpoint from the soap:address element. The dynamic setting allows me to change this up a bit and access the Web Service using a URL defined in the application configuration file in an appSetting key named Chapter2CLI.Chapter1.FirstService. Because I used the IDE, this key has already been placed in the app.config file. I can change this URL to hit my local machine by its name, scottnb, instead of by localhost. The appSettings section now looks like the following:

<appSettings>
    <add key="Chapter2CLI.Chapter1.FirstService"
        value="http://scottnb/Chapter1/FirstService.asmx"/>
</appSettings>