Table of Contents
The aim of this article is to give developers a complete set of steps that will allow them to setup their own isolated development environment for developing websites with ASP.NET, Subversion, and Windows XP.
Microsoft recommends developing ASP.NET web applications in an isolated development environment. For more information on the various kinds of development environments, read the chapter ASP.NET Web Application Development Models from the article Team Development with Visual Studio .NET and Visual SourceSafe.
For developers that already have their environment setup but are not using source control, this article provides simple steps on how to add this functionality to their setup. At the end of each section I have included an Errors section which lists common errors that can occur when performing the proceeding tasks.
The benefits of having a properly setup development environment come in many forms, and once you've used source control and seen how easy it is to setup, you'll wonder how you ever developed without it.
Some of the benefits of source control include:
- Easily scale the number of people working on a project
- Allow secure and efficient external access to projects for contractors and road warriors
- More robust file and project disaster recovery, no need to worry about "where did that file go?"
- Monitoring the quality of code being written, no more "who wrote this" questions need to be asked
- Easier workflow automation to reduce errors moving code between development, staging, and production.
The article covers topics such as:
- How do I setup my machine to be a local/isolated ASP.NET development environment?
- How do I setup source control for internal and external network access?
- How do I publish my website from a Subversion repository to my development server?
- How do I setup my ASP.NET project to have environment specific settings?
1.0 Setting up IIS 5.1 on Windows XP
The following steps will help you setup Internet Information Server (IIS) on Windows XP. You can read more about Windows XP and IIS here and information on Securing your IIS setup can be found here. This link provides some great information on setting up IIS on Windows XP Home Edition.
||First, we will check to see if IIS is installed, click on Start->Control Panel->Add or Remove Programs.
||Click on Add/Remove Windows Components on the left-hand-side bar.
||The Windows Component Wizard should pop up. Scroll down and check the box next to Internet Information Server (IIS), then click Next down the bottom of the wizard, and IIS will be installed.
||Click on the Internet Information Server (IIS) option and then the Details button. Check the box next to FrontPage 2000 Server Extensions. This is needed later on when you use Visual Studio with your local instance of IIS.
||Click on OK, and then click on the Next button to install IIS. You may need to insert your Windows XP CD at this time.
||To check that IIS is working correctly, open your browser and go to http://localhost. You should be presented with a page welcoming you to Microsoft Windows XP Professional and also another browser window with the IIS documentation.
Now that we have confirmed that IIS is running correctly, we need to temporarily change the port that IIS runs on so we can easily install Apache.
||Click on Start->Control Panel->Administrative Tools->Internet Information Services. This will bring up the IIS management console.
||On the left-hand-side, you will see a tree view, with the top part of the tree saying Internet Information Services. Below this will be the name of your computer. E.g., mine says: "VIRTUALXP (local computer)". Expand this tree, and you will see below a folder named Web Sites. Expand this folder, and you will see a folder named Default Web Site.
||Right click on the Default Web Site folder and select Properties from the menu that pops up.
||You will be presented with a config page entitled Default Web Site properties, and the default selected tab will be Web Site. Look for the option called TCP Port which will currently be set to a value of 80. Change this to 81 and then click OK.
||To ensure our change has worked, go to http://localhost:81 and you should see the same welcome page that you saw in 1.4. The Documentation window for IIS will also try to load but fail, ignore this for now.
2.0 Install Visual Studio .NET 2003
One of the benefits of developing ASP.NET websites using Visual Studio .NET 2003 is the power to debug web applications just like you would a desktop application. The Visual Studio .NET 2003 documentation can be found here and there's also a Visual Studio .Net 2003 support area available.
||You will need to ensure you have installed FrontPage 2000 Server Extensions as done in step 1.4. If you haven't and you try and install Visual Studio, it will prompt you again.
||Installing Visual Studio .NET 2003 is a simple process of following the present wizard, the items below summarise the steps you will take during the installation.
- Install the Visual Studio .NET Prerequisites
- Visual Studio .NET
- Product Documentation
- Service Releases
||Now that Visual Studio.NET is installed, create a simple test application and run it locally. This will ensure that IIS is configured correctly to run ASP.NET applications locally. You can now also practice debugging this application locally on your machine. For further reading on debugging Web applications on your local machine, read the tutorials Debugging an ASP.NET Web Application, Part I - Tracing and Debugging an ASP.NET Web Application, Part II - Debugging.
Visual Studio .NET has detected Web server is not running ASP.NET 1.1 [Microsoft KB article]
This error often occurs if you install Visual Studio after you have already installed IIS. Run the following from a command prompt to fix this:
Unable to start debugging on the web server. The project is not configured to be debugged [Microsoft KB article]
You need to add the following line to your web.config file in order to debug your ASP.NET application:
3.0 Setting up Apache 2.0 on Windows
Apache is an Open Source webserver, you can find the Apache 2.0 documentation here and a Apache 2.0 FAQ is available here. Download links for Apache 2.0.54 which is used in this tutorial are provided below.
||Download the Apache 2.0 install from apache.org, the correct mirror download site should already be selected for you. At the time of writing, the version we are using is Apache 2.0.54, and I will be using the Win32 binary (MSI installer), file name apache_2.0.54-win32-x86-no_ssl.msi [4.66 MB].
Please note: Versions lower than 2.0.54 won't work with Subversion 1.2 because of a bug in how Apache < 2.0.54 was built for Windows.
||Once downloaded, run the Apache installer and proceed through the first few pages of the set up wizard until you come to the Server Information page.
||The fields you have to fill in are as follows:
||Network Domain. Enter the DNS domain in which your server is or will be registered in. For example, if your server's full DNS name is server.mydomain.net, you would type mydomain.net here. If you are running this at home, then you could just use your name to keep things simple, i.e., mine would be binarysuperglue.com.
||Server Name: Your server's full DNS name. Going on our example above, I would type in apache.binarysuperglue.com.
||Administrator's Email Address: Enter the server administrator's or webmaster's email address here. This address will be displayed along with error messages to the client, by default.
||Install Apache HTTP Server 2.0 ....: Select the default radio button selected, For All Users on Port 80 as a Service. In this tutorial, we are going to be running Apache on port 81 as 80 will be used to run IIS. If you are installing Apache on a dedicated box, then use port 80.
||Once you have entered all those properties, click on the Next button.
||Please select a setup type: Select Typical, as this includes everything required except the source code and libraries for module development.
Then click on the Next button.
||Install Apache HTTP Server 2.0 to the folder: The default path is C:\Program Files\Apache Group under which a directory called Apache2 will be created by default. Unless you have a specific reason to change this, leave it as is.
Click Next and let Apache install, this should only take a minute or so.
||Once Apache has successfully installed you'll notice a tray icon, the tray icon should have a small green arrow in a white circle which indicates that Apache is running. You can easily Start/Stop/Restart Apache from here by left clicking on the icon. If you right click on the icon, you have the option to open the Apache Services Monitor and you can see the status of the Apache Web server there.
||Test that the Apache Web Server is running by entering http://localhost into your browser. You should receive a window with the title Test Page for Apache Installation and some information telling you that Apache has been installed successfully on your system. We now need to change the port that Apache is running on to 81, so that IIS can run on port 80.
||Select the tray icon for the Apache Services monitor, and select Apache2 and click on Stop.
||Now, change the port that IIS is running on back to 80, follow the steps in Section 1 if you need a refresher.
||Go to where you installed Apache (default location will be C:\Program Files\Apache Group\Apache2) and find the conf directory.
||Open up the file httpd.conf with a text editor, and scroll down until you find the Listen directive. The line you should find will look like: Listen 80, just change the 80 to 81 and save the file.
||Select the Apache Services tray icon again, and click on Apache2 and then Start.
||Test that Apache has been changed successfully to port 81, http://localhost:81. You should see the same success page as you saw in 3.6, it may take a few seconds for the page to come up as Apaches initialises.
The Apache service named reported the following error: this is not an Apache module DSO
This error was reported when Apache 2.2 was installed. I have tested everything with 2.0, I haven't updated the apache version yet. If someone does and gets it to work, let me know if you had any problems. I assumed it would be forward compatible.
4.0 Setting up Subversion on Windows
Subversion is an Open Source source control system. Check out this list of great Open Source software, where all the tools are centered around Software management and Engineering. If you know only very little about source control and/or Subversion, read the free book Version Control with Subversion and in particular chapters 1. Introduction, 2. Basic concepts, and 3. Guided Tour before you attempt the rest of this tutorial. If you have the time, read as much as you can so you are familiar with the way Subversion works and what it can do. There's also a Subversion FAQ available aswell.
||We are going to be using Subversion, version 1.2.3. Download the Windows installer from here. For other versions, visit here.
||Run the installer and proceed through the first few standard setup wizard pages until you come to the wizard screen that says Select Destination Location.
||When asked where you wish to install Subversion, the default directory will be C:\Program Files\Subversion. Unless you have a specific reason, leave the installation directory as default, and click Next.
||Select Start Menu folder: You are now asked where you wish the program shortcuts to be made. You can leave the default of "Subversion" OR you have the option of ticking the check box at the bottom of this window and not installing any shortcuts at all. Click Next.
||Select Additional Tasks: The first two additional tasks can be done at your discretion but ensure that the additional task under the heading "Apache Modules" called Install and configure Subversion modules.... is checked.
||You'll be presented with a summary of what is going to be installed, and just click Install. Shouldn't take longer than a minute to install. Once installed, just proceed through the last few steps of the Wizard. Subversion is now installed, and we can proceed to setup Apache.
5.0 Setting up Apache to recognise Subversion repositories
Now we need to ensure that Subversion and Apache can work together. Setting up Subversion and Apache to work together will make it easy for you to access your source control repositories from outside your network/behind a firewall and where necessary provide a much more simpler means of authenticating users to repositories.
||Open up the Apache httpd.conf file again, located in C:\Program Files\Apache Group\Apache2\conf\ if you used the default install.
||Create a directory on your C: drive called svn in which you will store your Subversion repositories. You may change this if you want to store them somewhere else.
||Scroll to the bottom of the file and add the following config information:
AuthName "Subversion repositories"
This config directive lets Apache know where your Subversion repositories are and where to find the authentication information for users trying to access the repository via Apache, e.g., http://localhost:81/svn. You can change the svn variable in the tag if you wish to use a different naming scheme. We now need to create users and passwords for those wishing to access the Repositories.
||Bring up a command window by going Start/Run, type in cmd, and navigate to your Apache installation directory, the default is C:\Program Files\Apache Group\Apache2\.
||Type bin\htpasswd -c passwd ralph (substitute “ralph” with the name of the user you wish to create). This command will create a new password passwd file and add the user ralph to it. Please note: When adding new users, ensure you remove the -c, otherwise you will destroy your current password file.
||You'll now be prompted to type the password twice for the user you have just created.
||You should be presented with a message saying Adding password for user ralph.
||Restart Apache by left clicking on the Apache Services tray icon, then click on Apache2, and then Restart.
||Copy the file C:\Program Files\Subversion\bin\libdb43.dll from the Subversion installation directory to the Apache modules directory, C:\Program Files\Apache Group\Apache2\modules\.
||Edit Apache's configuration file C:\Program Files\Apache Group\Apache2\conf\httpd.conf with a text editor such as Notepad and make the following changes:
||Uncomment (remove the '#' mark) from the the following lines, the first two should be next to each other in the config file:
#LoadModule dav_fs_module modules/mod_dav_fs.so
#LoadModule dav_module modules/mod_dav.so
Check that the following two lines were added to the end of the LoadModule section. These lines should exist as our Subversion installation should have taken care of it:
LoadModule dav_svn_module modules/mod_dav_svn.so
LoadModule authz_svn_module modules/mod_authz_svn.so
||Restart Apache as in 5.8.
||Now, test your Subversion/Apache configuration by opening a browser and going to http://localhost:81/svn.
||If successful, you should be prompted to authenticate with Apache, type in the username and password you created in 5.4. You should receive a message saying: Forbidden, You don't have permission to access /svn on this server, where svn can be substituted for the parameter you set in the directive in 5.3. Don't be worried about this message; since we haven't setup any repositories yet, this is normal. If you are getting errors, see the error section below.
Now, you can setup TortoiseSVN to create and modify your Subversion repositories from Windows Explorer.
Error: Authorization Required
You didn't get your username and password correct.
404 file not found
You may receive this message if you haven't set the directory correctly in step 5.1. Check that the directory you created to store your repositories in, is correctly entered in the Apache config.
6.0 Setting up TortoiseSVN
TortoiseSVN is one of the free Subversion Windows clients available. RapidSVN is an alternative and cross-platform client that quite a few people use although I haven't used it. The TortoiseSVN documentation can be found here and there's also a TortoiseSVN FAQ available aswell.
||You can download the Windows installer from here. For this tutorial, I used the version TortoiseSVN-220.127.116.1184-VS.NET-ASP.NET-svn-1.2.3.msi. However, since then the latest version of TortiseSVN has the .svn bug work around built into the client.
Note: working copies created by this version (and when you enable the .svn -> _svn directory work around) are incompatible with other Subversion clients!
||Run the installer and step through the installation wizard. You can leave all of the options on their default settings as per the picture below. You will be shown a change log, and you'll also need to reboot at the end of the installation.
||Once you have rebooted, you'll now notice a new context menu item when you right click on a directory in Windows Explorer.
Next, you'll learn to use TortoiseSVN to create repositories.
7.0 Creating Subversion repositories using TortoiseSVN
||Using Windows Explorer, navigate to the folder you created to store Subversion repositories, default is C:\svn\, and create a new directory with the name you want for your repository, say MyRepository. Use the name of your program or project you wish to store in Subversion.
||Right click on the new folder you just created, and select the menu option TortoiseSVN and another context menu will appear. Select Create Repository here.....
||You will be asked about the type of repository you wish to create, select Native File System, it should be the default. See Repository Data-Stores in the Subversion book regarding information on a comparison of the various repository types. You should be prompted with a message indicating that the repository was created successfully, and you should now see that some directories and files were created in C:\svn\Respository\.
||We now need to create the structure of your repository. It is highly recommended that you read Creating a Repository Layout in the Subversion book. This discusses issues like do I use one repository for all my projects or use individual repositories for each project. For simplicity, in this tutorial, we are going to assume you are creating one repository to hold one project.
||Create a directory in your C:\svn\ folder called repos_structure. This directory will contain the template directory structure, used to setup a new repository.
||Create three directories within repos_structure called trunk, branches, and tags.
||Right click on the directory repos_structure and select TortoiseSVN->Import.... Only the directories within this directory will be imported.
||You will be presented with an Import window. For the URL of the repository, use http://localhost:81/svn/MyRepository. Type a comment in the Import Message to signify that this is the initial directory import.
||Authentication window. Import window successful. You may experience a slight pause, and then you will see a log of what has been imported into Subversion.
||Go to http://localhost:81/svn/MyRepository/ and you'll see your imported directory structure. If it's your first time accessing the repository, you will be presented with an authentication window. Use the uername and password we created in Setting up Subversion and Apache in 5.4. You have the option of saving the authentication information. Now that your repository is all setup, you should practice adding, modifying, and deleting files from your Projects repository. Check out the TortoiseSVN Daily use guide as it covers areas such as Importing, Checking out, and Resolving conflicts with your repositories. I recommend you read the entire chapter or at least skim over it as there's lots of useful information.
Error Malformed URL for repository
Check that the URL you are using is correct, and that there's no missing /'s etc. Check that all the parameters of your
<Location> directive in the Apache config file are correct.
Error PROPFIND request failed on '/' PROPFIND of '/svn/': 403 Forbidden
Check that all the parameters of your
<Location> directive in the Apache config file are correct.
8.0 Setting up for ASP.NET website development on Windows XP
Now that you have Subversion setup to store all your website code, you may run into one little problem when developing on Windows XP. Windows XP can only run one website at a time. This can be very tedious when you are developing locally and need to constantly switch between web sites. Having to go into the IIS management console each time is very annoying. The steps below will allow a simple one click process, to switch the web sites home directory.
If all your websites can run within their own virtual directory, then the following setup doesn't apply to you.
You may (and often will) have sites that need to be placed in the root of the website directory in order to work correctly due to them having absolute links and not being .NET controls (style sheets, images etc).
This then presents a problem with running multiple websites on Windows XP. You can only run one website at a time with a true document root. In a future article, I'll show how you can run multiple websites on Windows XP, but for now, there's a way we can simplify switching the root directory of the local website running on your machine.
The following is an example directory structure of how you might check out numerous web sites from Subversion.
Once you have them checked out, to switch the root directory of your website running on your local machine, we are going to use some scripts to add an option to your Windows Explorer.
The steps you would take in switching between projects would be:
- Close Visual Studio (if already open)
- Switch the root to the directory you want to work on (right click-> Set IIS home)
- Open Visual Studio
- Open desired project file or solution
Note: You'll need to close your Visual Studio Solution/Project when switching between IIS home directories, you may receive an error as mentioned in the error section below if the steps above are not followed.
Follow the steps below to create a menu item in Windows Explorer to simplify switching the websites root folder.
||Let's say you have a directory called C:\websites where you will check out your web sites to work on them locally.
||Create the file set.iis.path.reg and save it to C:\Utils\. Copy and paste the commands below into the file. This entry provides us with a quick one step right click context menu option when you choose the directory you want to set as the IIS root. Run this file.
# set.iis.path.reg #
[HKEY_CLASSES_ROOT\Folder\shell\Set IIS home\command]
||Create the file set.iis.path.bat and save it to C:\Utils\. Copy and paste the commands below into the file.
# set.iis.path.bat #
SET /W3SVC/1/ROOT/Path "%1"
rmdir /s /q "C:\C:\Documents and Settings\Ralph\VSWebCache"
Ensure that the last line of the set.iis.path.bat file points to the Visual Studio cache directory of the user who you are logged on as.
When using Visual Studio .NET 2003 why do I see a little blue flag image/icon in the Visual Studio Explorer?
This is because the Visual Studio cache hasn't been deleted as Visual Studio keeps a cache of the last project you opened and is looking for these files.
Environment and developer specific settings
You can achieve environment specific settings using two web.config files, one is the primary settings file and another overrides the primary config file variables with environments specific values. The article Team Development with Visual Studio .NET and Visual SourceSafe gives a good example of how you can achieve this by storing a database connection string for two different environments. Read the chapter Managing Dependencies, and scroll down to the section Referencing Databases for example code.
9.0 Publishing Subversion Repositories using Windows XP/2000/2003
Now that you have your website(s) stored in Subversion, the following steps will help you automatically publish the contents of your repository to your development server. Subversion provides "hooks" for this process. These hooks allow you to trigger scripts or programs when certain events are raised by Subversion.
I've chosen to publish my repository to the development server anytime a user commits some changes. We'll use the post commit hook. You can, for example, hook scripts in the hook directory of where you created your Subversion repository. The hook scripts we created for this tutorial will be found in C:\svn\MyRepository\hooks\. Since we are using Windows, you can name your hook scripts .bat, .exe, .vbs etc.
I've created my hook scripts using bat files, if your not familiar with bat files the DOS batch file programming handbook and tutorial is a great place to start. You could also write VBS scripts or console apps depending on your skills and functional requirements.
To publish a Subversion repository, my bat file follows these steps:
- If the Subversion and development server are separate servers, map a drive from the Subversion server to the development server.
- Check out the repository you wish to publish to a temporary directory.
- Use Robocopy to mirror the temporarily checked out version of your website to the development server directory.
Robocopy is a very powerful utility for directory mirroring, and can be downloaded as part of the Windows Server 2003 Resource Kit Tools. Check out the documentation for other functionality it can provide.
This bat file assumes your Subversion server and development server are two different machines. If they are on the same machine, this obviously simplifies things and the drive mapping is not necessary.
# post-commit.bat #
REM The following variables are passed via the
REM command line to the hook script from Subversion
REM %1 -> Respository Name
REM %2 -> Revision number
REM Create our mapped drive as .bat files are run
REM by Subversion with NO environment variables set
net use Z: \\Server\TargetShare <pass>
/user:Server\<username> /persistent:no >> output.log
REM Check out our example repository to a tempoary directory
svn checkout file:///c:/svn/MyRepository/trunk C:\temp\Site1 >> output.log
REM Use Robocopy to mirror our directories
REM and exclude from the mirroring certain files and directories.
robocopy C:\temp\Site1 Z:\Site1\wwwroot *.* /S /XF *.cs *.tmp *.dbg
*.tmpl *.sln *.csproj *.webinfo /XD .svn _svn /PURGE >> output.log
Note: You'll notice in the script that we direct the output from the commands to a log file; this is handy for debugging, particularly when Subversion is running the script. Robocopy will pump out to the log file a nicely formatted dump of what files have been transferred and other additional info.
Your website has now been published to your development server minus all the unnecessary files.
29 Dec 2006
22 Aug 2006
- Created a better format for article layout
- Add some formatting that was removed when article was moved to Code Project
- Added Revision history
- Fixed up Error messages for each section and links to Microsoft KB articles
- Removed references section as it was out of context and put links into relevant sections
- Checked external links to ensure they still work
- 6.1 - updated as the new Tortise SVN client has option to work around .svn directory issue
- 7.10 - fixed some broken links to Subversion documentation