This documentation is archived and is not being maintained.

Walkthrough: Redirecting an Application to Target a Different XML Web Service During Installation

This walkthrough demonstrates how to create a Web application that can be redirected to target a different XML Web service by using the URL Behavior property, an Installer class, and a Web Setup project. This is useful when you need to target an XML Web service locally during development and want to use a production version of the XML Web service when your application is deployed.

Creating the Project

The first step is to create an ASP.NET Web Application project.

To create the project

Targeting a Different XML Web Service

In order to locate an XML Web service at run time, an application stores the URL for the XML Web service. The URL Behavior property of a Web reference for an XML Web service determines where the URL is stored. When the URL Behavior property is set to Static (the default), the URL is hard-coded as part of the Web reference. When the URL Behavior property is set to Dynamic, an entry specifying the URL is added to the appSettings section of the application's Web.config file.

To set the URL Behavior property to Dynamic

  1. In Solution Explorer, expand the Web References node and select the reference to the XML Web service.
  2. In the Properties window, select the URL Behavior property and change it to Dynamic.
  3. In Solution Explorer, select the Web.config file and double-click to open it.

    Near the end of the file you should find an <appSettings> section that contains a key that specifies the name of the XML Web service and a value that specifies the URL. For example, for an application named MyWebApp that accesses MyWebService on the local computer, it would look like:

    <appSettings><add key="MyWebApp.localhost.Service1" value=http://localhost/MyWebService/Service1.asmx/></appSettings>

Adding an Installer Class

Installer classes, also known as installation components, are .NET Framework classes that are invoked as custom actions during installation. In this case, you will add an Installer class and override its Install method, adding code to modify the .config file. For more information on Installer classes, see Introduction to Installation Components.

To add an Installer class

  1. On the Project menu, click Add New Item.
  2. In the Add New Item dialog box, select Installer Class and change the Name to WebServiceInstaller.

    When you click Open, the class will be added to your project and the designer for the Installer class will open.

  3. Double-click the designer to open the Code Editor.
  4. Add the following code for the Install method at the bottom of the Installer class module (just above the End Class declaration):
    Public Overrides Sub Install(ByVal stateSaver As _
       ' Gets the parameter passed across in the CustomActionData.
       Dim installlog As New System.IO.StreamWriter("Installation.log")
       installlog.AutoFlush = True
          Dim ProvidedName As String = _
          Dim SvcName As String = Me.Context.Parameters.Item("ServiceName")
          installlog.WriteLine("Starting Edit of the config file")
          If ProvidedName = "" Or SvcName = "" Then
             Throw New InstallException("No arguments specified")
          End If
          ' Uses reflection to find the location of the config file.
          Dim Asm As System.Reflection.Assembly = _
          Dim strConfigLoc As String
          strConfigLoc = Asm.Location
          Dim strTemp As String
          strTemp = strConfigLoc
          strTemp = strTemp.Remove(strTemp.LastIndexOf("\"), Len(strTemp) _
    – strTemp.LastIndexOf("\"))
          strTemp = strTemp.Remove(strTemp.LastIndexOf("\"), Len(strTemp) _
    – strTemp.LastIndexOf("\"))
          Dim FileInfo As System.IO.FileInfo = New _
    System.IO.FileInfo(strTemp & "\web.config")
          installlog.WriteLine("File info: " & strTemp)
          If Not FileInfo.Exists Then
             Throw New InstallException("Missing config file")
          End If
          ' Loads the config file into the XML DOM.
          Dim XmlDocument As New System.Xml.XmlDocument()
          ' Finds the right node and change it to the new value.
          Dim Node As System.Xml.XmlNode
          Dim FoundIt As Boolean = False
          For Each Node In 
             ' Skips any comments.
             If Node.Name = "add" Then
                If Node.Attributes.GetNamedItem("key").Value = _
    "appname.servername.service" Then
                   ' Note that "Service1.asmx" should be replaced with the
                   ' actual name of the XML Web service file.
                   Node.Attributes.GetNamedItem("value").Value = _
    "http://" & ProvidedName & "/" & SvcName & "/Service1.asmx"
                   FoundIt = True
                End If
             End If
          Next Node
          If Not FoundIt Then
             Throw New InstallException("Config file did not contain a _
    ServerName section")
             End If
             ' Writes out the new config file.
          installlog.WriteLine("Ending edit of config file")
       End Try
    End Sub

    The above code first creates an installation log file that will record the progress of the custom action. The System.Reflection namespace is used to locate the assembly that is being installed and to find the associated .config file. The XML document model is used to iterate through the .config file until the appSettings section is found. When the key appname.servername.service is found, its associated value is changed to include the parameters that were passed in, redirecting the application to use the new XML Web service.

  5. In Solution Explorer, double-click the Web.config file to open it.
  6. Copy the value of the key for your XML Web service in the appSettings section. The key takes the form appname.servername.service where appname is the name of your application, servername is the server where the XML Web service is located, and service is the name of the XML Web service.
  7. Open the Installer class module in the Code Editor and replace the text "appname.servername.service" with the value that you copied in the previous step.

Adding a Setup Project

Setup projects are used to create an installer for your application. Based on Windows Installer technology, setup projects include features such as the ability to run custom actions during installation and to customize the installation user interface. For more information on Setup projects, see Deploying Applications and Components.

To add a Setup project

  1. On the File menu, point to Add Project, then click New Project.
  2. In the Add New Project dialog box, select the Setup and Deployment Projects node in the Project Types pane.
  3. In the Templates pane, choose Web Setup Project and click OK.

    The project will be added to the solution and the File System Editor will be opened.

  4. In the Properties window, select the ProductName property and set it to the name of your application.
  5. In the File System Editor, select the Web Application Folder.
  6. On the Action menu, point to Add, then click Project Output.
  7. In the Add Project Output Group dialog box, select your application project; then select Primary output and Content Files and click OK.

Adding a Custom Action

Custom actions are used to run code at the end of an installation in order to perform actions that cannot be handled during installation. The code for a custom action can be contained in a .dll, .exe, script, or assembly file. For more information on custom actions, see Custom Actions Management in Deployment.

To add the Installer class as a custom action

  1. In Solution Explorer, select the Setup project.
  2. On the View menu, point to Editor, then click Custom Actions.

    The Custom Actions Editor opens.

  3. In the Custom Actions Editor, select the Install node.
  4. On the Action menu, choose Add Custom Action.
  5. Double-click the Web Application Folder, then select the Primary output node and click OK.
  6. In the Properties window, select the InstallerClass property and make sure that it is set to true.
  7. Select the CustomActionData property and enter the following text: /ServerName=[EDITA1] /ServiceName=[EDITA2]

    The CustomActionData property provides the two parameters that are passed to the custom action, separated by a space.

Adding a Dialog Box

User interface dialog boxes are displayed during installation to collect information from the user. For more information on user interface dialogs, see User Interface Management in Deployment.

To add a custom user interface dialog box

  1. In Solution Explorer, select the Setup project.
  2. On the View menu, point to Editor, then click User Interface.
  3. In the User Interface Editor, select the Start node under Install.
  4. On the Action menu, choose Add Dialog.
  5. In the Add Dialog dialog box, choose the Textboxes (A) dialog and click OK.
  6. On the Action menu, choose Move Up, and repeat until the Textboxes (A) dialog is located above the Installation Address dialog.
  7. In the Properties window, set the following properties:
    Property Value
    BannerText Enter the server name and service name
    Edit1Label Server Name:
    Edit1Value Localhost
    Note   This specifies a default server. You can enter your own default server name here.
    Edit2Label Service Name:
    Edit2Value <name of the service>
    Edit3Visible false
    Edit4Visible false

    Notice that the Edit1Property property is set to "EDITA1" and the Edit2Property property is set to "EDITA2". These correspond with the values that you entered in the CustomActionData property in the Custom Actions Editor. When the user enters text in these edit controls during installation, the values are automatically passed by means of the CustomActionData property.

Building and Deploying the Application

The final step is to build the Setup project in order to create the installer, then to install your application on the target server.

To build the Setup project

  • On the Build menu, choose Build Projectname, where Projectname is the name of your Setup project.

To deploy the application to a Web server on your development computer

  1. In Solution Explorer, select your Setup project.
  2. On the Project menu, click Install.

To deploy the application to a Web server on another computer

  1. In Windows Explorer, navigate to your project directory and find the built installer. The default path will be \documents and settings\yourloginname\My Documents\Visual Studio Projects\setupprojectname\project configuration\productname.msi. The default project configuration is Debug.
  2. Copy the .msi file and all other files and subdirectories in the directory to the Web server computer.
  3. On the Web server computer, double-click the Setup.exe file to run the installer.

See Also

Introduction to Installation Components | Deploying Applications and Components | Custom Actions Management in Deployment | User Interface Management in Deployment