使用 Elmah 來記錄 ASP.NET 網站的錯誤

使用 Elmah 來記錄和查看 ASP.NET 應用程式的 exception 相當方便好用，相關文章已經很多了，這裡僅重點摘錄一下個人使用的筆記。

建議使用 NuGet 來取得 Elmah 套件，因為它會自動幫你在 web.config 中加入一些必要的預設區段，像這樣：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <sectionGroup name="elmah">
      <section name="security" requirePermission="false" type="Elmah.SecuritySectionHandler, Elmah" />
      <section name="errorLog" requirePermission="false" type="Elmah.ErrorLogSectionHandler, Elmah" />
      <section name="errorMail" requirePermission="false" type="Elmah.ErrorMailSectionHandler, Elmah" />
      <section name="errorFilter" requirePermission="false" type="Elmah.ErrorFilterSectionHandler, Elmah" />
    </sectionGroup>
  </configSections>

  <system.web>
    <httpModules>
      <add name="ErrorLog" type="Elmah.ErrorLogModule, Elmah" />
      <add name="ErrorMail" type="Elmah.ErrorMailModule, Elmah" />
      <add name="ErrorFilter" type="Elmah.ErrorFilterModule, Elmah" />
    </httpModules>
  </system.web>

  <system.webServer>
    <validation validateIntegratedModeConfiguration="false" />
    <modules runAllManagedModulesForAllRequests="true">
      <add name="ErrorLog" type="Elmah.ErrorLogModule, Elmah" preCondition="managedHandler" />
      <add name="ErrorMail" type="Elmah.ErrorMailModule, Elmah" preCondition="managedHandler" />
      <add name="ErrorFilter" type="Elmah.ErrorFilterModule, Elmah" preCondition="managedHandler" />
    </modules>
    <handlers>
      <!-- 略 -->
    </handlers>
  </system.webServer>

  <elmah>
    <!--
        See http://code.google.com/p/elmah/wiki/SecuringErrorLogPages for 
        more information on remote access and securing ELMAH.
    -->
    <security allowRemoteAccess="true" />
  </elmah>

  <location path="elmah.axd" inheritInChildApplications="false">
    <system.web>
      <httpHandlers>
        <add verb="POST,GET,HEAD" path="elmah.axd" type="Elmah.ErrorLogPageFactory, Elmah" />
      </httpHandlers>
      <!-- 
        See http://code.google.com/p/elmah/wiki/SecuringErrorLogPages for 
        more information on using ASP.NET authorization securing ELMAH.
      <authorization>
        <allow roles="admin" />
        <deny users="*" />  
      </authorization>
      -->
    </system.web>
    <system.webServer>
      <handlers>
        <add name="ELMAH" verb="POST,GET,HEAD" path="elmah.axd" type="Elmah.ErrorLogPageFactory, Elmah" preCondition="integratedMode" />
      </handlers>
    </system.webServer>
  </location>
</configuration>

上述組態內容適用於 IIS 6/7。

可是預設的組態設定並不會產生 log， 我們還得定義要使用哪種方式來記錄網站的錯誤訊息，例如使用 XML 檔案、寄送 email、保存在資料庫等等。

底下的範例會令 Elmah 在捕捉到 exception 時，同時進行兩個記錄錯誤訊息的動作：

1. 將錯誤訊息儲存在網站根目錄下的 Log/Error 資料夾下的 XML 檔案，檔名會包含日期時間戳記。
2. 將錯誤訊息透過 email 寄送給指定的倒楣鬼收件人。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <elmah>
    <security allowRemoteAccess="false" />
    <errorLog type="Elmah.XmlFileErrorLog, Elmah" logPath="~/Log/Error" />
    <errorMail 
      from="michael@mycompany.com" 
      to="michael@mycompany.com" 
      subject="XX 網站又出包了!" 
      async="true"      
      smtpServer="mail.mycompany.com"
      smtpPort="25"
      />
  </elmah>
</configuration>

注意 Elmah 的 XML 記錄檔並不支援滾動式記錄（rolling log；檔案達到特定大小之後就把比較舊的記錄刪除，以免 log 檔無限長大）。

產品環境的組態檔

在產品環境時，我們可能會想要關閉某些 logging 機制。此時可利用組態檔轉換（transformation）的機制，在 Web.Release.config 中動手腳，參考底下的範例：

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <elmah>
    <errorMail xdt:Transform="Remove" />
  </elmah>
</configuration>

此範例會在專案以 Release 模式發布時，將 <elmah> 區段裡面的 <errorMail> 元素整個拿掉。

允許遠端存取 elmah.axd

在開發時期，我們可能希望所有團隊成員都能利用瀏覽器來查看錯誤訊息，此時可將 <elmah> 區段中的 security 元素的 allowRemoteAccess 屬性值由 false 改為 true。同時利用前述組態檔轉換的技巧，在 Web.Release.Config 中把 allowRemoteAccess 屬性值設定為 false，以限定只有在 app server 本機才能瀏覽 http://host_name/app_name/elmah.axd。

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <elmah>
    <security allowRemoteAccess="false" xdt:Transform="SetAttributes" />
    <errorMail xdt:Transform="Remove" />
  </elmah>  
</configuration>

下圖為使用瀏覽器查看網站錯誤記錄的畫面：

攔截 ASP.NET Web API 的錯誤

這個部分已經在先前的 Web API 筆記中提及，參見：ASP.NET Web API Exception Filter 的同場加映部分。

延伸閱讀

•  如何為網站錯誤記錄模組 Elmah 設定篩選器來過濾錯誤資訊
• ASP.NET保安系列 - 關於elmah.axd的安全設定