HttpErrorsSection Class
Configures HTTP error handling for a Web server.
Syntax
class HttpErrorsSection : ConfigurationSectionWithCollection
Methods
The following table lists the methods exposed by the HttpErrorsSection class.
| Name | Description |
|---|---|
| Add | (Inherited from ConfigurationSectionWithCollection.) |
| Clear | (Inherited from ConfigurationSectionWithCollection.) |
| Get | (Inherited from ConfigurationSectionWithCollection.) |
| GetAllowDefinition | (Inherited from ConfigurationSection.) |
| GetAllowLocation | (Inherited from ConfigurationSection.) |
| Remove | (Inherited from ConfigurationSectionWithCollection.) |
| RevertToParent | (Inherited from ConfigurationSection.) |
| SetAllowDefinition | (Inherited from ConfigurationSection.) |
| SetAllowLocation | (Inherited from ConfigurationSection.) |
Properties
The following table lists the properties exposed by the HttpErrorsSection class.
| Name | Description |
|---|---|
DefaultPath |
An optional string value that contains the default path of an HTTP error file or URL. When nonempty, this value is inherited by the Path property of newly created HttpErrorElement objects. |
DefaultResponseMode |
An optional sint32 value that configures the default response to HTTP errors. When nonempty, this value is inherited by the ResponseMode property of newly created HttpErrorElement objects. The possible values are listed later in the Remarks section. |
DetailedMoreInformationLink |
An optional read/write string value that specifies the URL for a link, shown at the bottom of the page, to a page with more detailed information about the error that was raised. The status, substatus, hresult, and messageid of the error are sent as part of the query string. You can use this property to point end users to a custom location for error information. The default is https://go.microsoft.com/fwlink/?LinkID=62293. |
ErrorMode |
A read/write sint32 enumeration that specifies whether the detailed error functionality is enabled, disabled, or shown only to local clients. The possible values are listed later in the Remarks section. |
ExistingResponse |
A read/write sint32 enumeration that specifies how IIS handles existing custom errors. The possible values are listed later in the Remarks section. |
HttpErrors |
An array of HttpErrorElement values that configure handling for specific HTTP errors. |
Location |
(Inherited from ConfigurationSection.) A key property. |
Path |
(Inherited from ConfigurationSection.) A key property. |
SectionInformation |
(Inherited from ConfigurationSection.) |
Subclasses
This class contains no subclasses.
Remarks
This class exposes the settings in the <httpErrors> section of a configuration file.
The custom errors represented by the HttpErrorsSection class are related to IIS 7 and are in the System.WebServer.Configuration namespace. Each of these errors is represented by an instance of the HttpErrorElement class.
The custom errors represented by the CustomErrorsSection class are specific to ASP.NET and are in the System.Web namespace. Each of these errors is represented by an instance of the CustomError class.
The following table lists the possible values for the DefaultResponseMode property. The default is 0 (File).
| Value | Keyword | Description |
|---|---|---|
| 0 | File |
The Web server returns the Web page from the static file specified in the Path property of the HttpErrorElement class. Note: Custom errors are language-specific and typically return the custom error in the language of the client. This requires that the client's language pack is installed. The file path is constructed as follows: PrefixLanguageFilePath\ClientLanguageID\ErrorCodeFile For example, if PrefixLanguageFilePath is "d:\inetpub\custerr", the client browser sends "en-us" in the Accept-Language header, and the error code is 404, the resulting path when the en-US language pack is installed is d:\inetpub\custerr\en-us\404.htm. If ja-JP is the system language, and the en-US language pack is not installed, the resulting path is d:\inetpub\custerr\ja-jp\404.htm. |
| 1 | ExecuteURL |
The Web server returns the internal ASP page specified in the Path property of the HttpErrorElement class. The URL should be in the scope of the same application pool. Note: In IIS 7, the redirection creates a URL with the following format (the items in the brackets are optional): /<CustomErrorPage>[?<QueryString>]&resourcePath=<OriginalURL>[?<OriginalQueryString>]&statusCode=<StatusCode> |
| 2 | Redirect |
The Web server provides an HTTP 302 Found response and includes the URL specified in the Path property of the HttpErrorElement class in the Location field of the response. If the response is a GET method instead of a HEAD method, it should also include an entity that has a short hyperlink to the new URL. Note: In IIS 7, the redirection creates a URL with the following format (the items in the brackets are optional): /<CustomErrorPage>[?<QueryString>]&resourcePath=<OriginalURL>[?<OriginalQueryString>]&statusCode=<StatusCode> |
The following table lists the possible values for the ErrorMode property. The default is 0 (DetailedLocalOnly).
| Value | Keyword | Description |
|---|---|---|
| 0 | DetailedLocalOnly |
A detailed error response is generated only if the request comes from the local computer. If the request comes from an external address, the server generates a custom error response. Note: The value of the ExistingResponse property determines whether a detailed or custom error is generated. |
| 1 | Custom |
The error that the module or server generates is replaced by a custom page that you specify. This mode is useful in providing friendlier error messages to end users. Note: This setting turns off detailed errors, even for local requests. |
| 2 | Detailed |
A page with detailed information about the application error is displayed, and custom errors are not shown. This mode is useful for testing and debugging Web sites and applications. Note: It is a security risk to set ErrorMode to Detailed, because even remote clients will receive detailed error information that could lead to unwanted information disclosure. |
The following table lists the possible values for the ExistingResponse property. The default is 0 (Auto).
| Value | Keyword | Description |
|---|---|---|
| 0 | Auto |
The response depends on the first successful match of the following set of ordered conditions: 1. If the IHttpResponse::SetStatus method was called by using the fTrySkipCustomErrors flag, the existing response is passed through, and no detailed or custom error is shown.2. If the ErrorMode property is set to Custom, the response is replaced.3. If ErrorMode is set to Detailed and there is an existing response, the response is passed through.4. If ErrorMode is set to Detailed and there is no existing response, the response is replaced with a detailed error. |
| 1 | Replace |
The existing response is always replaced, regardless of how SetStatus was called. |
| 2 | PassThrough |
The existing response is always used. |
Example
The following code example specifies new values for the DefaultPath, ErrorMode, and DetailedMoreInformationLink properties. A helper function displays the configuration section values before and after the change.
' Connect to the WMI WebAdministration namespace.
Set oWebAdmin = GetObject("winmgmts:root\WebAdministration")
' Get the HTTP errors section.
Set oSection = oWebAdmin.Get( _
"HttpErrorsSection.Path='" & _
"MACHINE/WEBROOT/APPHOST/',Location=''")
' Display the class name of the section.
WScript.Echo "[ " & oSection.Path_.Class & " ]"
' Display the initial values.
Call DisplayValues("Initial Values", oSection)
' Specify the path of a default error page.
oSection.DefaultPath = _
"D:\inetpub\custerr\en-US\contoso\DefaultErrorPage.htm"
' Specify a detailed more information link.
oSection.DetailedMoreInformationLink = "http://www.contoso.com/MoreInfo.htm"
'Set the ErrorMode property to Custom.
oSection.ErrorMode = 1
' Save the values to configuration.
oSection.Put_
' Refresh the oSection object variable with the new values.
oSection.Refresh_
' Display the changed values.
Call DisplayValues("New Values", oSection)
' ==== DisplayValues helper function. ====
Function DisplayValues(HeadingText, oSection)
' Display a heading.
WScript.Echo
WScript.Echo HeadingText
WScript.Echo String(Len(HeadingText), "-")
' Display the non-embedded section properties.
For Each prop In oSection.Properties_
If Left( _
Prop.Qualifiers_("CIMTYPE"), 6) _
<> "object" then
WScript.Echo prop.Name & ": " & prop.Value
End If
Next
End Function
Inheritance Hierarchy
ConfigurationSectionWithCollection
HttpErrorsSection
Requirements
| Type | Description |
|---|---|
| Client | - IIS 7.0 on Windows Vista - IIS 7.5 on Windows 7 - IIS 8.0 on Windows 8 - IIS 10.0 on Windows 10 |
| Server | - IIS 7.0 on Windows Server 2008 - IIS 7.5 on Windows Server 2008 R2 - IIS 8.0 on Windows Server 2012 - IIS 8.5 on Windows Server 2012 R2 - IIS 10.0 on Windows Server 2016 |
| Product | - IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0 |
| MOF file | WebAdministration.mof |
See Also
ConfigurationSection Class
ConfigurationSectionWithCollection Class
CustomError Class
CustomErrorsSection Class
HttpErrorElement Class
IHttpResponse::SetStatus Method
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for