June 27, 2014

Taking Your ASP.NET Site Offline with App_Offline.htm

Have you ever wanted to display a friendly maintenance page to users while updating or performing some sort of work on your website? It could be that you are rolling out an upgrade to your site or maybe you are tweaking some IIS settings or making some major changes to your database or infrastructure.

ASP.NET 2.0 introduced a simple yet powerful feature that is still available today. It is as simple as adding a single file to your website.

Basically, if you place a file with the name 'app_offline.htm' in the root of your web application directory, ASP.NET will shut-down the application, and stop processing any new incoming requests for that application.

ASP.NET will also then respond to all requests for dynamic pages in the application by sending back the content of the app_offline.htm file (for example: you might want to have a “site under construction” or “down for maintenance” message).

After the maintenance is complete just delete the App_Offline.htm file and the site will return back to normal.
A few points to consider:        
  • Prevent Friendly Http Errors - Some browsers like to be helpful and display their own custom error pages for HTTP errors like 404 and 500.  These errors are triggered when the page returned by the server is very short, typically less than 512 bytes.  To prevent this make sure the size of the app_offline.htm file is greater than 512 bytes. Add some comments to the file to make sure the byte size is greater than 512 and it will work fine.          
  • CSS, Images & JavaScript - If you want your offline page to look nice, any CSS and JavaScript will have to be embedded in the page.  In addition if you want images, you will have to use the Base-64 encode trick and include it using a data URI. 

Sample Project - I created a sample MVC 4 project on GitHub called AppOfflineify to demonstrate this feature.
To test it out copy the file App_Offline.htm in the Tools folder to the root and run the project.

Generating Maintenance Pages - If you would like to generate maintenance pages automatically there is a cool site which will help you do this. 

May 24, 2014

Effective Bug Reports Require Good Communication

"If I went back to college again, I'd concentrate on two areas: learning to write and to speak before an audience. Nothing in life is more important than the ability to communicate effectively."

Gerald R. Ford

With all of the advances in science and technology it seems that one of the basic skills that many have difficulty with is communication. This causes a serious challenge at the workplace because communication is a basic building block required for just about everything we do.

For instance think about the last project you worked on. Whether you were gathering the requirements with product owners, working with the creative team designing the user experience or working with the technical team building the architecture and code - this all required one common denominator: good communication.

One area where poor communication causes a lot of problems for a software project is bug reports. Good bug reports that communicate effectively to a developer can make a big difference.

"It doesn't work."

How often have we looked at a bug report  and the only information there is something like "It doesn't work", or "it's broken".  If you want to quickly drive your software developers to Lovecraftian madness then please keep creating bug reports like this. Poorly written bug reports kill productivity. 

Think about it, if you were to bring your car to a mechanic and say "it doesn't work" how would they be able to diagnose the problem? You would need to tell the mechanic what the problem is, details explaining how you observed the problem and what you expect. In a similar way a good bug report should do exactly the same.

Therefore if you are pragmatic and want to improve in this area then communicating well in bug reports is essential. So what makes a good bug report? In simple terms one that clearly explains what the problem is, how did it happen and what was expected to happen. If a bug report  does not satisfy all of these criteria in a concise, simple manner then it has failed.  The following is a check list for an effective bug report:

- Short Summary

- Steps To Reproduce

- Expected Behavior

- One bug per ticket

- Include Test Data

- Provide Screenshots / Screen Cast