HTTP-Fehler <httpErrors>
Übersicht
Das <httpErrors>-Element ermöglicht die Konfiguration benutzerdefinierter Fehlermeldungen für Ihre Website oder Anwendung. Mit benutzerdefinierten Fehlermeldungen können Sie eine benutzerfreundlichere bzw. aussagekräftigere Antwort zurückgeben, wenn Besucher Ihrer Website nicht auf den angeforderten Inhalt zugreifen können. Hierzu können Sie eine Datei bereitstellen, eine andere Ressource zurückgeben oder Besucher zu einer URL umleiten. So können Sie beispielsweise alle Seiten mit Fehlermeldungen an das Erscheinungsbild Ihrer Website anpassen.
Das <httpErrors>-Element enthält eine Sammlung von <error>-Elementen, die jeweils eine Fehlermeldung definieren, die IIS verwendet, um auf bestimmte HTTP-Fehler zu reagieren. Sie können IIS benutzerdefinierte Fehlermeldungen hinzufügen, indem Sie dem <httpErrors>-Element in der Datei „Web.config“ für Ihre Site, Anwendung oder URL ein <error>-Element hinzufügen. Jedes <error>-Element verwendet das responseMode-Attribut, um anzugeben, ob IIS als Reaktion auf einen Fehler statische Inhalte, dynamische Inhalte oder Umleitungen zu einer separaten URL bereitstellen soll.
Sie können das <remove>-Element verwenden, um eine bestimmte Fehlermeldung aus der Sammlung von Fehlermeldungen zu entfernen, die Ihre Site oder Anwendung von einer höheren Ebene in der IIS-Konfigurationshierarchie erbt. Mit dem <clear>-Element können Sie außerdem alle HTTP-Fehlermeldungen aus der Sammlung von HTTP-Fehlermeldungen entfernen, die Ihre Site oder Anwendung erbt.
Das <httpErrors>-Element enthält auch Attribute, die IIS 7 für die Verarbeitung von Anforderungen konfigurieren, die Fehler verursachen. Das existingResponse-Attribut definiert, wie IIS 7 mit einer vorhandenen Antwort verfahren soll, wenn der Server einen HTTP-Fehlerstatuscode zurückgibt. Das defaultPath-Attribut definiert den Pfad zu einer Kundenfehlerseite, wenn Sie für das responseMode-Attribut in einem <error>-Element die Option File angeben.
Das detailedMoreInformationLink-Attribut gibt einen Link zu weiteren Informationen im Zusammenhang mit einem bestimmten Fehler an.
Das <httpErrors>-Element kann auch ein errorMode-Attribut enthalten, um zu steuern, wie viele Details IIS im Falle eines HTTP-Fehlers an einen Browser zurückgeben soll. Das errorMode-Attribut kann auf DetailedLocalOnly (Standardeinstellung) oder auf Custom oder Detailed festgelegt werden. Wenn Sie DetailedLocalOnly angeben oder keinen errorMode-Wert angeben, gibt IIS ausführliche Fehlerinformationen nur an den Browser auf dem lokalen Server und eine benutzerdefinierte Fehlermeldung an einen Browser auf einem externen Computer zurück. Wenn Sie den errorMode-Wert auf Custom festlegen, gibt IIS nur benutzerdefinierte Fehlermeldungen an alle anfordernden Browser zurück. Wenn Sie den errorMode-Wert auf Detailed festlegen, gibt IIS ausführliche Fehlerinformationen an alle anfordernden Browser zurück. Der Standardwert DetailedLocalOnly ermöglicht es Ihnen, HTTP-Fehler auf dem lokalen Server zu behandeln, ohne vertrauliche Informationen für externe Browser verfügbar zu machen.
Standardmäßig stellt IIS Fehlermeldungen bereit, die in Dateien im Ordner „%SystemRoot%\Help\IisHelp\Common“ definiert sind. Sie können eine benutzerdefinierte Fehlermeldung für Benutzer erstellen und IIS so konfigurieren, dass diese Seite zurückgegeben wird, wenn ein bestimmter HTTP-Fehler für Ihre Site auftritt.
Kompatibilität
| Version | Hinweise |
|---|---|
| IIS 10.0 | Das <httpErrors>-Element wurde in IIS 10.0 nicht geändert. |
| IIS 8.5 | Das <httpErrors>-Element wurde in IIS 8.5 nicht geändert. |
| IIS 8.0 | Das <httpErrors>-Element wurde in IIS 8.0 nicht geändert. |
| IIS 7.5 | Das allowAbsolutePathsWhenDelegated-Attribut wurde dem <httpErrors>-Element in IIS 7.5 hinzugefügt. |
| IIS 7.0 | Das <httpErrors>-Element wurde in IIS 7.0 eingeführt. |
| IIS 6.0 | Das <httpErrors>-Element ersetzt die HttpErrors-Eigenschaft des IIsWebService-Metabasisobjekts von IIS 6.0. |
Setup
Das <httpErrors>-Element ist in der Standardinstallation von IIS 7 enthalten.
Gewusst wie
Hinzufügen einer benutzerdefinierten Fehlerseite
Öffnen Sie Internetinformationsdienste-Manager (IIS-Manager):
Vorgehensweise unter Windows Server 2012 oder Windows Server 2012 R2:
- Klicken Sie auf der Taskleiste auf Server-Manager > Tools > Internetinformationsdienste-Manager (IIS-Manager).
Vorgehensweise unter Windows 8 oder Windows 8.1:
- Halten Sie die WINDOWS-TASTE gedrückt, drücken Sie den Buchstaben X, und klicken Sie dann auf Systemsteuerung.
- Klicken Sie auf Verwaltung, und doppelklicken Sie dann auf Internetinformationsdienste-Manager (IIS-Manager).
Vorgehensweise unter Windows Server 2008 oder Windows Server 2008 R2:
- Klicken Sie auf der Taskleiste auf Start, zeigen Sie auf Verwaltung, und klicken Sie dann auf Internetinformationsdienste-Manager (IIS-Manager).
Vorgehensweise unter Windows Vista oder Windows 7:
- Klicken Sie auf der Taskleiste auf Start und dann auf Systemsteuerung.
- Doppelklicken Sie auf Verwaltung, und doppelklicken Sie dann auf Internetinformationsdienste-Manager (IIS-Manager).
Erweitern Sie im Bereich Verbindungen den Servernamen, erweitern Sie Sites, und navigieren Sie dann zu der Website oder Anwendung, für die Sie benutzerdefinierte Fehlerseiten konfigurieren möchten.
Doppelklicken Sie im Bereich Start auf Fehlerseiten.
Klicken Sie im Bereich Aktionen auf Hinzufügen....
Geben Sie im Dialogfeld Benutzerdefinierte Fehlerseite hinzufügen unter Statuscode die Nummer des HTTP-Statuscodes ein, für den Sie eine benutzerdefinierte Fehlermeldung erstellen möchten.
Führen Sie im Abschnitt Antwortaktion eine der folgenden Aktionen aus:
- Wählen Sie Inhalt aus statischer Datei in die Fehlerantwort einfügen aus, um statischen Inhalt (z. B. eine HTML-Datei) für den benutzerdefinierten Fehler bereitzustellen.
- Wählen Sie URL auf dieser Site ausführen aus, um dynamischen Inhalte (z. B. eine ASP-Datei) für den benutzerdefinierten Fehler bereitzustellen.
- Wählen Sie Mit einer Umleitung vom Typ „302“ reagieren aus, um Clientbrowser zu einer anderen URL umzuleiten, die die benutzerdefinierte Fehlerdatei enthält.
Geben Sie im Textfeld Dateipfad den Pfad der benutzerdefinierten Fehlerseite ein, wenn Sie Inhalt aus statischer Datei in die Fehlerantwort einfügen ausgewählt haben, oder geben Sie die URL der benutzerdefinierten Fehlerseite ein, wenn Sie entweder URL auf dieser Site ausführen oder Mit einer Umleitung vom Typ „302“ reagieren ausgewählt haben, und klicken Sie anschließend auf OK.
Hinweis
Bei Verwendung von URL auf dieser Site ausführen muss der Pfad ein relativer Pfad sein. Bei Verwendung von Mit einer Umleitung vom Typ „302“ reagieren muss die URL eine absolute URL sein.
Konfiguration
Das <httpErrors>-Element kann auf der Serverebene in der Datei „ApplicationHost.config“ und auf der Site- und Anwendungsebene in der entsprechenden Datei vom Typ „Web.config“ konfiguriert werden.
Attribute
| Attribut | Beschreibung | ||||||||
|---|---|---|---|---|---|---|---|---|---|
allowAbsolutePathsWhenDelegated |
Optionales boolesches Attribut. Wenn dieses Attribut auf true festgelegt ist, sind absolute Pfade für benutzerdefinierte Fehlerseiten zulässig, wenn der <httpErrors>-Abschnitt delegiert wird. Wenn dieses Attribut auf false festgelegt ist, sind nur Pfade relativ zum Stammverzeichnis der Site zulässig.Der Standardwert ist false. |
||||||||
defaultPath |
Optionales Zeichenfolgeattribut. Gibt den Standardpfad der benutzerdefinierten Fehlerseite an. Der Pfadtyp wird durch das defaultResponseMode-Attribut bestimmt. Bei Verwendung von File wird der Dateipfad zurückgegeben. Bei Verwendung des Pfadtyps ExecuteURL oder Redirect wird die URL der benutzerdefinierten Fehlerseite zurückgegeben. |
||||||||
defaultResponseMode |
Optionales enum-Attribut. Gibt an, wie benutzerdefinierte Fehlerinhalte zurückgegeben werden. Das defaultResponseMode-Attribut kann einen der folgenden Werte haben. Der Standardwert ist File.
|
||||||||
detailedMoreInformationLink |
Optionales Zeichenfolgeattribut. Gibt einen Link zu einer Seite mit ausführlichen Informationen zu einem bestimmten Fehler an. Dieser Link wird unten auf der Seite angezeigt. Sie können diese Eigenschaft verwenden, um auf einen benutzerdefinierten Ort mit Fehlerinformationen für Endbenutzer zu verweisen. Status, Unterstatus, HRESULT und Nachrichten-ID werden als Teil der Abfragezeichenfolge gesendet. Der Standardwert ist https://go.microsoft.com/fwlink/?LinkID=62293. |
||||||||
errorMode |
Optionales enum-Attribut. Gibt an, ob HTTP-Fehler aktiviert sind. Das errorMode-Attribut kann einen der folgenden Werte haben. Der Standardwert ist DetailedLocalOnly.
|
||||||||
existingResponse |
Optionales enum-Attribut. Gibt an, was mit einer vorhandenen Antwort passiert, wenn es sich bei dem HTTP-Statuscode um einen Fehler (Antwortcodes >= 400) handelt. Das existingResponse-Attribut kann einen der folgenden Werte haben. Der Standardwert ist Auto.
|
Untergeordnete Elemente
| Element | Beschreibung |
|---|---|
error |
Optionales Element. Fügt der Sammlung von HTTP-Fehlern einen HTTP-Fehler hinzu. |
remove |
Optionales Element. Entfernt einen Verweis auf einen HTTP-Fehler aus der HTTP-Fehlersammlung. |
clear |
Optionales Element. Entfernt alle Verweise auf HTTP-Fehler aus der HTTP-Fehlersammlung. |
Konfigurationsbeispiel
Wenn das folgende Konfigurationsbeispiel in die Datei „Web.config“ für eine Website oder Anwendung eingeschlossen wird, wird das errorMode-Attribut verwendet, um die Anzeige ausführlicher Fehlermeldungen nur auf dem lokalen Computer zuzulassen. Außerdem wird das defaultResponseMode-Attribut verwendet, um den Antwortmodus für die Site oder Anwendung festzulegen. Anschließend wird in dem Beispiel die geerbte Fehlermeldung für den Statuscode 500 entfernt. Danach wird das prefixLanguageFilePath-Attribut auf das Verzeichnis festgelegt, in dem IIS nach einer neuen benutzerdefinierten Fehlerseite suchen soll, und das path-Attribut wird auf „500.htm“ (die Datei, die die benutzerdefinierte Fehlermeldung enthält) festgelegt.
<configuration>
<system.webServer>
<httpErrors errorMode="DetailedLocalOnly" defaultResponseMode="File" >
<remove statusCode="500" />
<error statusCode="500"
prefixLanguageFilePath="C:\Contoso\Content\errors"
path="500.htm" />
</httpErrors>
</system.webServer>
</configuration>
Beispielcode
In den folgenden Beispielen wird eine neue Datei für alle Fehler mit dem Statuscode 404 und dem Unterstatus 5 hinzugefügt, den IIS für Fehler vom Typ „Abgelehnte URL-Sequenz“ zurückgibt. In diesen Beispielen wird der Präfixpfad auf „%SystemDrive%\inetpub\custerr“ festgelegt, und als Dateiname wird „404.5.htm“ angegeben.
AppCmd.exe
appcmd.exe set config -section:system.webServer/httpErrors /+"[statusCode='404',subStatusCode='5',prefixLanguageFilePath='%SystemDrive%\inetpub\custerr',path='404.5.htm']" /commit:apphost
Hinweis
Legen Sie den commit-Parameter auf apphost fest, wenn Sie „AppCmd.exe“ verwenden, um diese Einstellungen zu konfigurieren. Dadurch werden die Konfigurationseinstellungen auf den entsprechenden Speicherortabschnitt in der Datei „ApplicationHost.config“ festgelegt.
C#
using System;
using System.Text;
using Microsoft.Web.Administration;
internal static class Sample
{
private static void Main()
{
using (ServerManager serverManager = new ServerManager())
{
Configuration config = serverManager.GetApplicationHostConfiguration();
ConfigurationSection httpErrorsSection = config.GetSection("system.webServer/httpErrors");
ConfigurationElementCollection httpErrorsCollection = httpErrorsSection.GetCollection();
ConfigurationElement errorElement = httpErrorsCollection.CreateElement("error");
errorElement["statusCode"] = 404;
errorElement["subStatusCode"] = 5;
errorElement["prefixLanguageFilePath"] = @"%SystemDrive%\inetpub\custerr";
errorElement["path"] = @"404.5.htm";
httpErrorsCollection.Add(errorElement);
serverManager.CommitChanges();
}
}
}
VB.NET
Imports System
Imports System.Text
Imports Microsoft.Web.Administration
Module Sample
Sub Main()
Dim serverManager As ServerManager = New ServerManager
Dim config As Configuration = serverManager.GetApplicationHostConfiguration
Dim httpErrorsSection As ConfigurationSection = config.GetSection("system.webServer/httpErrors")
Dim httpErrorsCollection As ConfigurationElementCollection = httpErrorsSection.GetCollection
Dim errorElement As ConfigurationElement = httpErrorsCollection.CreateElement("error")
errorElement("statusCode") = 404
errorElement("subStatusCode") = 5
errorElement("prefixLanguageFilePath") = "%SystemDrive%\inetpub\custerr"
errorElement("path") = "404.5.htm"
httpErrorsCollection.Add(errorElement)
serverManager.CommitChanges()
End Sub
End Module
JavaScript
var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST");
var httpErrorsCollection = httpErrorsSection.Collection;
var errorElement = httpErrorsCollection.CreateNewElement("error");
errorElement.Properties.Item("statusCode").Value = 404;
errorElement.Properties.Item("subStatusCode").Value = 5;
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\\inetpub\\custerr";
errorElement.Properties.Item("path").Value = "404.5.htm";
httpErrorsCollection.AddElement(errorElement);
adminManager.CommitChanges();
VBScript
Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST")
Set httpErrorsCollection = httpErrorsSection.Collection
Set errorElement = httpErrorsCollection.CreateNewElement("error")
errorElement.Properties.Item("statusCode").Value = 404
errorElement.Properties.Item("subStatusCode").Value = 5
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\inetpub\custerr"
errorElement.Properties.Item("path").Value = "404.5.htm"
httpErrorsCollection.AddElement errorElement
adminManager.CommitChanges()