customErrors Element (ASP.NET Settings Schema)

Artikel
12/21/2012

Provides information about custom error messages for an ASP.NET application. The customErrors element can be defined at any level in the application file hierarchy.

<configuration> Element
system.web Element (ASP.NET Settings Schema)
<customErrors>

<customErrors defaultRedirect="url"
              mode="On|Off|RemoteOnly">
     <error. . ./>
</customErrors>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute	Description
defaultRedirect	Optional attribute. Specifies the default URL to direct a browser to, if an error occurs. When this attribute is not specified, a generic error is displayed instead. The URL can be absolute (for example, www.contoso.com/ErrorPage.htm) or relative. A relative URL, such as /ErrorPage.htm, is relative to the Web.config file that specified the URL for this attribute, not to the Web page in which the error occurred. A URL starting with a tilde (~), such as ~/ErrorPage.htm, indicates that the specified URL is relative to the root path of the application.
mode	Required attribute. Specifies whether custom errors are enabled, disabled, or shown only to remote clients. This attribute can be one of the following values. ValueDescription On Specifies that custom errors are enabled. If no defaultRedirect attribute is specified, users see a generic error. The custom errors are shown to the remote clients and to the local host. Off Specifies that custom errors are disabled. The detailed ASP.NET errors are shown to the remote clients and to the local host. RemoteOnly Specifies that custom errors are shown only to the remote clients, and that ASP.NET errors are shown to the local host. This is the default value. The default is RemoteOnly.
redirectMode	Optional attribute. Specifies values for how the URL of the original request is handled when a custom error page is displayed. This attribute can be one of the following values. ValueDescription ResponseRedirect Specifies that the URL to direct the browser to must be different from the original Web request URL. ResponseRewrite Specifies that the URL to direct the browser to must be the original Web request URL.

defaultRedirect

Optional attribute.

Specifies the default URL to direct a browser to, if an error occurs. When this attribute is not specified, a generic error is displayed instead.

The URL can be absolute (for example, www.contoso.com/ErrorPage.htm) or relative. A relative URL, such as /ErrorPage.htm, is relative to the Web.config file that specified the URL for this attribute, not to the Web page in which the error occurred. A URL starting with a tilde (~), such as ~/ErrorPage.htm, indicates that the specified URL is relative to the root path of the application.

mode

Required attribute.

Specifies whether custom errors are enabled, disabled, or shown only to remote clients.

This attribute can be one of the following values.

ValueDescription

On Specifies that custom errors are enabled. If no defaultRedirect attribute is specified, users see a generic error. The custom errors are shown to the remote clients and to the local host.

Off Specifies that custom errors are disabled. The detailed ASP.NET errors are shown to the remote clients and to the local host.

RemoteOnly Specifies that custom errors are shown only to the remote clients, and that ASP.NET errors are shown to the local host. This is the default value.

The default is RemoteOnly.

redirectMode

Optional attribute.

Specifies values for how the URL of the original request is handled when a custom error page is displayed.

This attribute can be one of the following values.

ValueDescription

ResponseRedirect Specifies that the URL to direct the browser to must be different from the original Web request URL.

ResponseRewrite Specifies that the URL to direct the browser to must be the original Web request URL.

Child Elements

Element	Description
error	Optional element. Specifies the custom error page for a given HTTP status code. The error tag can appear multiple times. Each appearance defines one custom error condition.

error

Optional element.

Specifies the custom error page for a given HTTP status code.

The error tag can appear multiple times. Each appearance defines one custom error condition.

Parent Elements

Element	Description
configuration	Specifies the root element in every configuration file that is used by the common language runtime and the .NET Framework applications.
system.web	Specifies the root element for the ASP.NET configuration settings in a configuration file and contains configuration elements that configure ASP.NET Web applications and control how the applications behave.

Remarks

Default Configuration

The following default customErrors element is configured in the Machine.config file in the .NET Framework versions 1.0 and 1.1.

<customErrors mode="RemoteOnly" />

Example

The following configuration example demonstrates how to specify the error handling pages to use for an ASP.NET application.

<configuration>
  <system.web>
    <customErrors defaultRedirect="GenericError.htm"
                  mode="RemoteOnly">
      <error statusCode="500"
             redirect="InternalError.htm"/>
    </customErrors>
  </system.web>
</configuration>

Element Information

Configuration section handler	System.Web.Configuration.CustomErrorsSection
Configuration member	SystemWebSectionGroup.CustomErrors System.Web.Configuration.CustomErrorsMode
Configurable locations	Machine.config Root-level Web.config Application-level Web.config Virtual or physical directory–level Web.config
Requirements	Microsoft Internet Information Services (IIS) version 5.0, 5.1, or 6.0 The .NET Framework version 1.0, 1.1, or 2.0 Microsoft Visual Studio 2003 or Visual Studio 2005

Delen via

customErrors Element (ASP.NET Settings Schema)

Attributes and Elements

Attributes

Child Elements

Parent Elements

Remarks

Default Configuration

Example

Element Information

See Also

Tasks

Reference

Concepts

Other Resources

Aanvullende resources