ErrorHandler is an EASY to USE and FUN open source ASP.NET error (Exception) logging and reporting solution developed by Ted Kolovos, creator of CSharpUniversity.com. You can download and start using it right now. Keep reading to learn more.
What does ErrorHandler do for me?
- Easily add error logging functionality to your web application in a plug and play fashion. No more need to design and create your own custom logging database tables or code your own error logger.
- Provides a web interface to search and view the errors that were logged by your web application.
(click to enlarge)
Why was this project created?
- Web programmers want a simple, repeatable way to log errors when they occur.
- Web programmers want something lightweight and very easy to use because time is critical on development projects. I’m also a big believer in the “5 minute setup”.
- Web programmers like to customize things so that’s why I’m providing it as open source in case that need arises. Most people will be able to use it “as is, out of the box”.
How does the ErrorHandler work?
The ErrorHandler project consists of two pieces of software:
- A class library assembly (.dll) called csharpuniversity.ErrorTracking. ErrorTracking contains methods that you can call from your application code to save errors to the logging database.
- A website application called csharpuniversity.ErrorWeb. ErrorWeb is an interface that you can use to search and view the contents of the error log database.
How can I setup the ErrorHandler software and start using it?
Please follow the step-by-step setup instructions below and watch the videos that I’ve included to assist you.
1) The first thing you need to do is create the “errorlog” database table. You can either create the table yourself in a SQL Server database that you already have or you can import the database file that I have provided.
Video: Create the errorlog table in an existing database using the “errorlog_tables.sql” file. The errorlog_tables.sql file contains the table specification.
OR you can do this…
Video: Restore the errorlog database backup file “errortracking_CSharpUniversity.bak”. This will create a new database that contains the errorlog table. It doesn’t matter what you call the new database when you restore it because later you will be customizing the connection string when you call the ErrorHandler assembly from your code. You can create as many error logging databases as you need. Each application needs to point to its own database.
2) Next you need to test the ErrorTracking assembly and make sure it is able to connect and write to the errorlog database table. To help with this I’ve included a test tool website project called “ErrorLogTest”. This test project has a few different web pages in it:
- Test Single Random Exception - Writes one randomized test error to the errorlog.
- Test Multiple Random Exceptions - Writes several randomized test errors to the errorlog.
- Test Native Exception - Writes one test exception to the errorlog. This exception looks more like a regular native exception that would occur as your application is running in product.
To run the ErrorLogTest website, you need to change the “errortracking_CSharpUniversity” connection string in the web.config file to match your environment. Notice in the sample video below that I changed the database name in the connection string to “ErrorDB”.
Video: Test the ErrorTracking assembly connectivity and make sure it can write to the errorlog table.
If the test screens don’t encounter any problems writing to the errorlog, then you can proceed to the next step since you’ve verified that the ErrorTracking assembly is working and able to write to the database table.
3) Next you need to run the csharpuniversity.ErrorWeb website and make sure it can view the errorlog. You need to change the “errortracking_CSharpUniversity” connection string in the web.config file to match your environment. Also change the value of the “ApplicationName” setting in web.config to match your application’s name. The start page (default) for the website should be set to ErrorTracking.aspx.
Video: Setup and run the ErrorWeb website. You can use the ErrorWeb website as you are developing an application to monitor the error log. It can also be used in deployment environments such as testing and production environments.
If you point the ErrorWeb website to the same database that you wrote the test records to in step 2 above, you should be able to see the test records returned as search results. After you have verified that ErrorWeb is working, you may choose to delete the test records from your errorlog database so that later you don’t confuse them with actual application exceptions.
4) Now you are at the final step: using the csharpuniversity.ErrorTracking.dll in your website. Follow these final instructions:
4a) You need to reference the “csharpuniversity.ErrorTracking.dll” file in your web project. You can do this in Visual Studio by right clicking on your project name and choosing Add Reference, click Browse and locate the dll file. Visual Studio will copy the file to your project’s “bin” folder.
4b) Add a connection string for the errorlog database in your web.config file. Please use the appropriate server name, database name, userID, etc. that match your environment.
<connectionStrings> <add name="errortracking_CSharpUniversity" connectionString="Server=localhost;Database=ErrorDB; User ID=sa;Password=Sqlserverpass$123; Trusted_Connection=False;"/> </connectionStrings>
4c) Call the “saveError” method wherever you normally catch exceptions. Here is an example where I’m calling saveError in a catch() block:
catch (Exception ex)
{
int ErrorId = csharpuniversity.ErrorTracking.ErrorLog.saveError(
ConfigurationManager.ConnectionStrings["errortracking_CSharpUniversity"].ConnectionString,
ex.Message,
DateTime.Now,
ex.StackTrace,
this.GetType().Name + "::" + ex.TargetSite.Name,
Request.UserHostAddress, Server.MachineName,
null, null, null, null, null
);
}
Video: How to use the ErrorTracking assembly in your website. In this video, I created a brand new website called TedsTestApp and in one of the try/catch blocks I added code that calls the ErrorTracking assembly.
Can you give me more detailed usage information about csharpuniversity.ErrorTracking?
In order to write an error to the errorlog database you should use saveError(…) method. saveError takes several input parameters that are described in detail below.
Method name: csharpuniversity.ErrorTracking.ErrorLog.saveError
Description: Saves ASP.NET Exception information into the database table “errorlog”. In addition to the error message and stacktrace, this method accepts additional parameters that contain pertinent additional information about the error.
| Parameter | Must pass a value | Max Length | Description |
|---|---|---|---|
| DBConnString | Yes | N/A | Connection string to the database that contains the [errorlog] table |
| ErrMessage | Yes | 1000 | The error message |
| TimeOccured | Yes | N/A | The date/time that the error occured |
| StackTrace | No | 4000 | The exception stack trace |
| Location | No | 1000 | The location/module/URL where the error occured |
| ClientIP | No | 30 | The client IP address of the web page user |
| ServerName | No | 250 | The web server name/IP where the error occured |
| Custom1 | No | 1000 | Generic parameter 1. These generic parameters can be used as needed for your custom needs. |
| Custom2 | No | 1000 | Generic parameter 2 |
| Custom3 | No | 1000 | Generic parameter 3 |
| Custom4 | No | 1000 | Generic parameter 4 |
| Custom5 | No | 1000 | Generic parameter 5 |
Return Value: The saveError method returns an Integer value that represents the unique error_id of the newly created errorlog database table record. One way you can use the error_id is to show it on a standard error page in your website so that the user can reference it if they call/email your customer service department to report a problem with your website. You can locate the error at anytime by entering the error_id in the ErrorWeb website.
Where can I see some more sample source code for calling the ErrorTracking assembly?
The ErrorLogTest project (that is included) contains full source code examples for the saveError() method that you can learn from.
Can you give me more information about csharpuniversity.ErrorWeb?
The ErrorWeb ErrorTracking.aspx page gives you several options for searching and viewing the errorlog. You can do a quick search that gives you the ability to see the error messages quickly without having to type in any search criteria. Quick search lets you see the most recent 100 or 500 errors. Quick search also gives you the ability to see all of the errors for the past 7 days. If you are unit testing your application code on a development server, quick search can really help give you the information that you need fast.
The other type of search you can do is a custom search. With a custom search you can search using any of the available criteria such as Error Id, Error Message, Date Range, etc. You can choose whether to do an Exact Match search or a Partial Match (SQL “like var%”) search. You can choose whether to show the newest records first or the oldest first. You can specify the maximum number of records to return. The default is 500 records.
How many applications can I use ErrorHandler with?
You can use ErrorHandler with as many applications as you need. The only thing you need to do is setup a separate “errorlog” table for each application. You also will need to create a separate running instance of the ErrorWeb website in your web server so that each instance can point to its own different errorlog database. Also configure the web.config file for each separate instance of ErrorWeb accordingly.
Can you give me a quick description of the files that are included with this project?
| File/Folder | Description |
|---|---|
| csharpuniversity.ErrorTracking.dll | The ErrorTracking assembly. This is the file that you should reference in your website project. |
| csharpuniversity.ErrorTracking | Folder containing the source code for the ErrorTracking assembly. |
| errorlog_tables.sql | Contains the SQL table description of the errorlog table. |
| errortracking_CSharpUniversity.bak | Database file that contains the errorlog table. You can restore this file to your SQL Server. |
| csharpuniversity.ErrorWeb | Folder containing the ErrorWeb website source code files. |
| ErrorLogTest | Folder containing the source code for the ErrorTracking test website. |
What database engine do I need in order to use ErrorHandler?
ErrorHandler writes and reads to a SQL Server database so you need to have the SQL Server Database Engine. The database can be installed on a different computer than your web server.
Can I change the code?
Yes, provided that you adhere to the license terms. The main reason that I made this an open source project is so that you can customize the project if necessary to better suit your needs. Many people will be able to benefit from the project without any additional modifications, but at least you have that option if you need it. If you would like to become an official developer on the main open source project itself, then you can request so by using CodePlex (visit download link below for more information).
Can I share copies of the software with my friends, coworkers and classmates?
Yes, as long as you adhere to the license terms. I like to share and I encourage you to share too.
Where can I download csharpuniversity.ErrorHandler?
.
