How to securely configure ELMAH with email alerts in IIS7

Over the prior two weeks we have had a number of server upgrade projects. Most have been moving from server 2003 to server 2008 R2. During the process I followed the basic installation instructions which involve modifying the web.config file manually. I couldn't get the same instructions to work for me when trying to integrate ELMAH into the new Server 2008 R2 environment. That is when I remembered that IIS7 wants to "help" us more by controlling the web.config settings via the IIS7 MMC Snap-in. Here is what I did to successfully get ELMAH working on Server 2008 R2.

1. Download the latest version of ELMAH from: http://code.google.com/p/elmah/downloads/list

2. Copy the Elmah.dll into the web application's /bin directory

Note: Make sure you copy the appropriate assembly for your server's CPU architecture (x86 x64)

3. Open up the IIS7 MMC Console

4. Select the site you want to add ELMAH to from the Tree View on the left

5. In the Features View:

a. Choose the Modules icon in the Features View

6. On the right, under Actions, choose "Add Managed Module…"

7. In the Add Managed Module window:

a. Type into the Name textbox: ErrorLog

b. Choose from the Type drop down list: Elmah.ErrorLogModule

8. For a second time choose "Add Managed Module…" from the right column

9. In the Add Managed Module window:

a. Type into the Name textbox: ErrorMail

b. Choose from the Type drop down list: Elmah.ErrorMailModule

10. Note: you should now have two new modules listed under Modules in the Features View

11. Click on the Website you are editing in the treeview on the left

12. Choose the Handler Mappings menu from the Features View

13. Under the Actions menu:

a. Click the Add Managed Handler… menu option

14. In the Add Managed Handler window:

a. Type into the Request Path textbox: /admin/elmah.axd

b. Type into the Type drop down list: Elmah.ErrorLogPageFactory

Note: the Elmah.ErrorLogPageFactory must be typed, it is not available via the drop down list

c. Type into the Name field: Elmah

15. Click the Back button to return to the Features View

16. From the Features View

a. Double-click the Authentication icon

17. In the Authentication window:

a. Highlight Windows Authentication

b. Click the Enable link from the Actions menu

Note: this might require an IISReset (I had a "HTTP 503 Service Unavailable" error on my Production server but not on my Development server, an IISRESET fixed my issue)

18. Browse to the web.config file and open it in Notepad

19. Find the </configSections> XML node and insert an empty line above it to add the following Section Group

<sectionGroup name="elmah">

      <section name="security" requirePermission="false" type="Elmah.SecuritySectionHandler, Elmah" />

      <section name="errorMail" requirePermission="false" type="Elmah.ErrorMailSectionHandler, Elmah" />
</sectionGroup>

20. Following the </configSections> XML node insert the <errorMail> configuration node:

<elmah>
    <security allowRemoteAccess="yes" />
    <errorMail
      from="webmaster@domain.com"
      to="SendTo@domain.com"
      subject="Message Subject"
      async="true"
      smtpPort="25"
      smtpServer="emailServerFQDN_OrIP" />

</elmah>

21. Customize the <errorMail> node properties to match your Organization's needs

22. Finally, go all the way to the bottom and insert the following before the last </configuration> XML node

<location path="admin">

    <system.web>

      <authorization>

        <deny users="?" />

      </authorization>

    </system.web>

</location>

Note: this section secures the /admin/ URL so only authorized users can view the /admin/elmah.axd page

Now, time to test the results.

23. Navigate to http://yoursite.com/admin/elmah.axd

24. The page will prompt you for credentials

25. Login with your user account

26. Verify the ELMAH default error page will display

27. Fire off a test exception by adding /test after your current URL (example: http://yourseite.com/admin/elmah.axd/test)

28. A test exception page will appear and might look similar to this

29. Navigate back to the ELMAH default error page: http://yoursite.com/admin/elmah.axd

30. The exception will be listed in the exceptions table as a test, and if you configured the email section properly you should receive an email including the exception details