Wednesday, November 22, 2006
Debug ASP.NET 2.0 running under IIS 6.0
Visual Studio 2005 Professional or Team Edition can perform remote debugging of an ASP.NET 2.0 Web Forms application running in its prime deployment environment, Internet Information Services (IIS) 6.0 on a Windows Server 2003 R2 platform. However, sloppy Microsoft technical writers and their dimwitted managers have made it a labor of experimental programming to find out how to do this. Their documentation on the topic is scattered across many articles and notes, omitting critical information that may be known to some Microsoft insiders but will be neither known nor obvious to experienced application developers and system administrators. We found that an MSDN support engineer could not explain how to do remote debugging under IIS 6.0 and that so-called "experts" from the MSDN Visual Studio Debugger Forum could not explain it either.
A key element is that to debug remotely the server running IIS 6.0 and the development machine running Visual Studio 2005 (Pro or Team) must have Administrator accounts with the same user name and password. The Visual Studio Remote Debugger must be started on the server or run as a service under this user name and password, and the user at the development machine must be logged in under the same user name and password. Otherwise Visual Studio 2005 will fail to connect with the server. Some Microsoft documentation claims that the server must be operating in a network domain, but that is not necessary. A domain is a convenient way to distribute account identification, but the server can also be in a workgroup. Visual Studio Remote Debugger must be installed on the server directly from Visual Studio 2005 Pro or Team media, either CD or DVD. Some Microsoft documentation claims it can be installed from a development computer, but that is not true with any standard installation of Visual Studio 2005.
Installation of Visual Studio Remote Debugger is provided by rdbgsetup.exe, located on the CD "Disc 2" in the Remote Debugger directory and on the DVD in the vs\Remote Debugger directory and in the x86, x64 or IA64 subdirectory that matches the server processor. An installation wizard provides an option to install a service. With that approach, it is necessary to visit the Visual Studio Remote Debugger service from Control Panel/Administrative Tools/Services and bring up a context menu with the alternate mouse button to access its Property page. On the Property page under the Log On tab enter the key user name and password, and under the General tab change Start Up from Disabled to Manual or Automatic. After exiting the Property page start the server from the context menu. If not installed as a service in this way, the Visual Studio Remote Debugger must be started prior to debugging by logging on the server under the key user name and password and launching msvsmon.exe from directory \Program Files\Microsoft Visual Studio 8\Common7\IDE\Remote Debugger on the system drive and the subdirectory that matches the server processor.
To debug an application running under IIS 6.0, source code must be placed on the server. A published build with source code only on the development machine but not on the server will not debug. By using a server share, Visual Studio 2005 can access an application Web site’s directories on the server and will build the application. A permission error that it may report at the end of the build can be ignored. Before building, the Debug option must be included in the web.config file for the application. Before debugging, an option in the IIS properties for the application must also be enabled. This is found by visiting Control Panel/Administrative Services/Internet Information Services, expanding Web Sites, selecting the application and then selecting Properties from a context menu. Under the ASP.NET tab, the Edit Configuration button brings up an ASP.NET Configuration Settings dialog. Under the Application tab of this dialog the Enable Debugging option must be checked.
Before trying to debug, make sure that the application pool and Web site are running by looking on the server using Control Panel/Administrative Services/Internet Information Services and checking the status shown when selecting Application Pools and Web Sites. If either is not running, select it and start it from a context menu. Using Visual Studio 2005 on a development machine, bring up the source code for the application that is located on the server. In this view of the application, breakpoints can be set in the code. Attach Visual Studio 2005 to the IIS 6.0 worker process, using Debug/Attach to Process. The appropriate Transport option is Default, and the Qualifier option is the network name of the server. The IIS 6.0 worker process under Available Processes will have the name w3wp.exe. Select this process and click the Attach button. Launch the application from the development machine by pointing Internet Explorer to the Web site, using its network address. Visual Studio 2005 does not do this automatically. When the code reaches a breakpoint, Visual Studio 2005 will show the same debugging display that it does when using its built-in server and will step through the code and show watchpoint information in the same ways.
While debugging under IIS 6.0, the worker process is stopped whenever the code is on break. That causes any other session or Web site in the same IIS 6.0 application pool to stop. For this reason, it is best to perform remote debugging with a dedicated test server, if available, or to set up a separate application pool for testing.
A key element is that to debug remotely the server running IIS 6.0 and the development machine running Visual Studio 2005 (Pro or Team) must have Administrator accounts with the same user name and password. The Visual Studio Remote Debugger must be started on the server or run as a service under this user name and password, and the user at the development machine must be logged in under the same user name and password. Otherwise Visual Studio 2005 will fail to connect with the server. Some Microsoft documentation claims that the server must be operating in a network domain, but that is not necessary. A domain is a convenient way to distribute account identification, but the server can also be in a workgroup. Visual Studio Remote Debugger must be installed on the server directly from Visual Studio 2005 Pro or Team media, either CD or DVD. Some Microsoft documentation claims it can be installed from a development computer, but that is not true with any standard installation of Visual Studio 2005.
Installation of Visual Studio Remote Debugger is provided by rdbgsetup.exe, located on the CD "Disc 2" in the Remote Debugger directory and on the DVD in the vs\Remote Debugger directory and in the x86, x64 or IA64 subdirectory that matches the server processor. An installation wizard provides an option to install a service. With that approach, it is necessary to visit the Visual Studio Remote Debugger service from Control Panel/Administrative Tools/Services and bring up a context menu with the alternate mouse button to access its Property page. On the Property page under the Log On tab enter the key user name and password, and under the General tab change Start Up from Disabled to Manual or Automatic. After exiting the Property page start the server from the context menu. If not installed as a service in this way, the Visual Studio Remote Debugger must be started prior to debugging by logging on the server under the key user name and password and launching msvsmon.exe from directory \Program Files\Microsoft Visual Studio 8\Common7\IDE\Remote Debugger on the system drive and the subdirectory that matches the server processor.
To debug an application running under IIS 6.0, source code must be placed on the server. A published build with source code only on the development machine but not on the server will not debug. By using a server share, Visual Studio 2005 can access an application Web site’s directories on the server and will build the application. A permission error that it may report at the end of the build can be ignored. Before building, the Debug option must be included in the web.config file for the application. Before debugging, an option in the IIS properties for the application must also be enabled. This is found by visiting Control Panel/Administrative Services/Internet Information Services, expanding Web Sites, selecting the application and then selecting Properties from a context menu. Under the ASP.NET tab, the Edit Configuration button brings up an ASP.NET Configuration Settings dialog. Under the Application tab of this dialog the Enable Debugging option must be checked.
Before trying to debug, make sure that the application pool and Web site are running by looking on the server using Control Panel/Administrative Services/Internet Information Services and checking the status shown when selecting Application Pools and Web Sites. If either is not running, select it and start it from a context menu. Using Visual Studio 2005 on a development machine, bring up the source code for the application that is located on the server. In this view of the application, breakpoints can be set in the code. Attach Visual Studio 2005 to the IIS 6.0 worker process, using Debug/Attach to Process. The appropriate Transport option is Default, and the Qualifier option is the network name of the server. The IIS 6.0 worker process under Available Processes will have the name w3wp.exe. Select this process and click the Attach button. Launch the application from the development machine by pointing Internet Explorer to the Web site, using its network address. Visual Studio 2005 does not do this automatically. When the code reaches a breakpoint, Visual Studio 2005 will show the same debugging display that it does when using its built-in server and will step through the code and show watchpoint information in the same ways.
While debugging under IIS 6.0, the worker process is stopped whenever the code is on break. That causes any other session or Web site in the same IIS 6.0 application pool to stop. For this reason, it is best to perform remote debugging with a dedicated test server, if available, or to set up a separate application pool for testing.
Subscribe to Posts [Atom]