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

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

Note

The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Visual Studio Settings.

Creating the Web Application Project

The first step is to create an ASP.NET Web Application project that contains a Web reference to a Web service.

To create the project

• Create a Web application that has a Web reference to a Web service. A Web reference to any valid Web service will suffice for this walkthrough. For example, you can use the Web application described in Walkthrough: Accessing a Web Service Using Visual Basic or Visual C#.

Adding an Installer Class

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

To create the class library project

1. Right-click the solution node in Solution Explorer and click Add, then New Project.

2. In the Add New Project dialog box, in the Visual Basic node, select Class Library.

3. Name the project InstallerClassLibrary.

To add and implement an Installer class

1. Right-click the InstallerClassLibrary project node in Solution Explorer and click Add, then Class.

2. In the Add New Item dialog box, select Installer Class and change the Name to WebServiceInstaller.vb.

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

3. Double-click the designer to open the Code Editor.

4. In WebServiceInstaller.vb, add the following code at the bottom of the Installer class module (just above the End Class declaration); this code implements the Install method:

   Public Overrides Sub Install(ByVal stateSaver As _
     System.Collections.IDictionary)
   
      ' Gets the parameter passed across in the CustomActionData.
      Dim installlog As New System.IO.StreamWriter("Installation.log")
      installlog.AutoFlush = True
      Try
        Dim ProvidedName As String = Me.Context.Parameters.Item("ServerName")
        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 = _
           System.Reflection.Assembly.GetExecutingAssembly
         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()
         XmlDocument.Load(FileInfo.FullName)
   
         ' 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 _
            XmlDocument.Item("configuration").Item("appSettings")
            ' Skips any comments.
            If Node.Name = "add" Then
               If Node.Attributes.GetNamedItem("key").Value = _
                  "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 = "https://" _
                    & 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.
         XmlDocument.Save(FileInfo.FullName)
   
      Finally
         installlog.WriteLine("Ending edit of config file")
         installlog.Close()
      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 servername.service is found, its associated value is changed to include the parameters that were passed in, redirecting the application to use the new Web service.

5. In Solution Explorer, double-click the Web.config file to open it.

6. Copy the value of the key for your Web service in the appSettings section. The key takes the form servername.service where servername is the server where the Web service is located, and service is the name of the Web service.

7. Open the Installer class module in the Code Editor and replace the text "servername.service" with the value that you copied in the previous step.

Adding a Web 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 Web Setup project

1. Right-click the solution node in Solution Explorer and click Add, then New Project.

2. In the Add New Project dialog box, in the Project Types pane, expand the Other Project Types node, then select the Setup and Deployment Projects node.

   In the Templates pane, select Web Setup Project. In the Name box, name the project WebAppSetup.

   When you click OK, the project will be added to the solution and the File System Editor will be opened.

3. In the Properties window, select the ProductName Property and set it to the name of your Web application.

4. In the File System Editor, select the Web Application Folder.

5. On the Action menu, point to Add, then click Project Output.

6. In the Add Project Output Group dialog box, select InstallerClassLibrary from the Project drop-down list; then select Primary Output.

   When you click OK, the primary output from InstallerClassLibrary will be added to the Web Setup project.

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 WebAppSetup project.

2. On the View menu, click Editor, then 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 Primary output from InstallerClassLibrary (Active).

6. In the Properties window, make sure that the InstallerClass property 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, and 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

Concepts

Introduction to Installation Components

Other Resources

Deploying Applications and Components

Custom Actions Management in Deployment

User Interface Management in Deployment