Handler <handlers>
Übersicht
Das <handlers>-Element definiert die Handler, die für eine bestimmte Dateinamenerweiterung oder URL registriert sind.
Handler sind IIS-Komponenten (Internet Information Services, Internetinformationsdienste), die für die Verarbeitung von Anforderungen für bestimmte Inhalte konfiguriert sind (in der Regel, um eine Antwort für die Anforderungsressource zu generieren). Ein Beispiel für einen Handlertyp ist etwa eine ASP.NET-Webseite. Sie können Handler verwenden, um Anforderungen für eine beliebige Ressource zu verarbeiten, die Informationen an Benutzer zurückgeben muss, bei denen es sich nicht um eine statische Datei handelt. IIS stellt verschiedene Handlertypen bereit, um statische Dateien, CGI-Anwendungen (Common Gateway Interface, gemeinsame Gatewayschnittstelle), FastCGI-Anwendungen und ISAPI-Erweiterungen (Internetserver-API) zu unterstützen. ASP.NET unterstützt auch weitere Handlertypen über die HTTP-Handlerschnittstelle.
Entwickler können benutzerdefinierte Handler erstellen, um eine besondere Behandlung durchzuführen, die Sie mithilfe von Dateinamenerweiterungen in Ihrer Anwendung identifizieren können. Wenn ein Entwickler beispielsweise einen Handler erstellt hat, der XML-Code im RSS-Format erstellt hat, können Sie die Dateinamenerweiterung „.rss“ in Ihrer Anwendung an den benutzerdefinierten Handler binden. Entwickler können auch Handler erstellen, die einer bestimmten Datei zugeordnet sind, und diese Handler als native Module oder als Implementierungen der IHttpHandler-Schnittstelle von ASP.NET implementieren.
Kompatibilität
| Version | Hinweise |
|---|---|
| IIS 10.0 | Das <handlers>-Element wurde in IIS 10.0 nicht geändert. |
| IIS 8.5 | Das <handlers>-Element wurde in IIS 8.5 nicht geändert. |
| IIS 8.0 | Das <handlers>-Element wurde in IIS 8.0 nicht geändert. |
| IIS 7.5 | Das <handlers>-Element wurde in IIS 7.5 nicht geändert. |
| IIS 7.0 | Das <handlers>-Element wurde in IIS 7.0 eingeführt. |
| IIS 6.0 | N/V |
Setup
Das <handlers>-Element ist in der Standardinstallation von IIS 7 enthalten.
Gewusst wie
Erstellen einer Handlerzuordnung für einen ASP.NET-Handler in einer IIS 7-Anwendung, die im integrierten Modus ausgeführt wird
Ö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).
Klicken Sie im Bereich Verbindungen auf die Serververbindung, der Sie das native Modul hinzufügen möchten.
Doppelklicken Sie im Bereich Start auf Handlerzuordnungen.
Klicken Sie im Bereich Aktionen auf Verwalteten Handler hinzufügen....
Geben Sie im Dialogfeld Verwalteten Handler hinzufügen Folgendes an:
Anforderungspfad: Der zuzuordnende Dateiname oder die zuzuordnende Dateinamenerweiterung.
Typ: Der Typname (Klasse) des verwalteten Handlers. Wenn der Handler im Ordner „app_code“ oder „bin“ der Anwendung definiert ist, wird sein Typname in der Dropdownliste angezeigt.
Name: Ein beschreibender Name.
Klicken Sie auf OK, um das Dialogfeld Verwalteten Handler hinzufügen zu schließen.
Erstellen einer FastCGI-Handlerzuordnung
Ö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).
Klicken Sie im Bereich Verbindungen auf den Servernamen, für den Sie FastCGI-Handlerzuordnungen konfigurieren möchten.
Doppelklicken Sie im Bereich Start auf Handlerzuordnungen.
Klicken Sie im Bereich Aktionen auf Modulzuordnung hinzufügen....
Hinweis
Damit die nächsten Schritte funktionieren, müssen Sie bereits Binärdateien installiert haben, die den von Ihnen angegebenen Dateipfad oder die von Ihnen angegebene Dateinamenerweiterung ausführen. In diesem Beispiel wird eine PHP-Implementierung verwendet, die auf der Microsoft-Website verfügbar ist.
Geben Sie die Dateinamenerweiterung (z. B. „as.php“) in das Feld Anforderungspfad ein, klicken Sie in der Dropdownliste Modul auf FastCGIModule, geben Sie den Pfad zur Skript-Engine (in diesem Beispiel „PHP-CGI.exe“) in das Feld Ausführbare Datei ein, und klicken Sie anschließend auf OK.
Klicken Sie im Dialogfeld Modulzuordnung hinzufügen auf Ja.
Konfiguration
Das <handlers>-Element enthält eine Sammlung von <add>-Elementen, die jeweils eine Handlerzuordnung für die Anwendung definieren. Das <add>-Element enthält unter anderem den Namen des Handlers, die Dateinamenerweiterung oder die URL-Pfadmaske, der der Handler zugeordnet ist, sowie den Modulnamen oder ASP.NET-HTTP-Handlertyp, der die Handlerimplementierung angibt.
Das <handlers>-Element wird auf der Anwendungsebene in der Datei „Web.config“ konfiguriert.
Attribute
| Attribut | Beschreibung | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
accessPolicy |
Optionales flags-Attribut. Gibt die zulässigen Zugriffstypen für die gesamte Handlersammlung an. Das accessPolicy-Attribut kann einen der folgenden Werte haben. Der Standardwert ist Read.
|
Untergeordnete Elemente
| Element | Beschreibung |
|---|---|
add |
Optionales Element. Fügt der Handlersammlung einen Handler hinzu. |
clear |
Optionales Element. Entfernt alle Verweise auf Handler aus der Handlersammlung. |
remove |
Optionales Element. Entfernt einen Verweis auf einen Handler aus der Handlersammlung. |
Konfigurationsbeispiel
Das folgende Beispiel enthält zwei <add>-Elemente, die Handlerzuordnungen definieren. Das erste <add>-Element definiert einen SampleHandler-Handler für eine Webanwendung, die im integrierten Modus von IIS 7 ausgeführt wird. Wenn Sie die Handlerassembly dem Verzeichnis „app_code“ für die Webanwendung hinzufügen, müssen Sie den Assemblynamen nicht in den Wert für das type-Attribut einschließen. Das zweite <add>-Element definiert eine Zuordnung für PHP-Anforderungen, die das FastCGI-Modul verwenden.
<handlers>
<add name="SampleHandler" verb="*"
path="SampleHandler.new"
type="SampleHandler, SampleHandlerAssembly"
resourceType="Unspecified" />
<add name="PHP-FastCGI" verb="*"
path="*.php"
modules="FastCgiModule"
scriptProcessor="c:\php\php-cgi.exe"
resourceType="Either" />
</handlers>
Beispielcode
In den folgenden Beispielen wird eine FastCGI-Zuordnung für ein PHP-Modul und anschließend ein Handler für die Contoso-Website hinzugefügt, der PHP-Anforderungen verarbeitet.
AppCmd.exe
appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='c:\php\php-cgi.exe']" /commit:apphost
appcmd.exe set config "Contoso" -section:system.webServer/handlers /+"[name='PHP-FastCGI',path='*.php',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='c:\php\php-cgi.exe',resourceType='Either']"
Hinweis
In diesem zweiten Beispiel wird gezeigt, wie Sie einer Webanwendung eine neue ASP.NET-Handlerzuordnung namens „SampleHandler.new“ für eine bestimmte URL hinzufügen.
appcmd.exe set config /section:system.webServer/handlers /+[name=SampleHandler',path='SampleHandler.new',verb='*',type='SampleHandler']
C#
using System;
using System.Text;
using Microsoft.Web.Administration;
internal static class Sample
{
private static void Main()
{
using (ServerManager serverManager = new ServerManager())
{
Configuration appHostConfig = serverManager.GetApplicationHostConfiguration();
ConfigurationSection fastCgiSection = appHostConfig.GetSection("system.webServer/fastCgi");
ConfigurationElementCollection fastCgiCollection = fastCgiSection.GetCollection();
ConfigurationElement applicationElement = fastCgiCollection.CreateElement("application");
applicationElement["fullPath"] = @"c:\php\php-cgi.exe";
fastCgiCollection.Add(applicationElement);
Configuration webConfig = serverManager.GetWebConfiguration("Contoso");
ConfigurationSection handlersSection = webConfig.GetSection("system.webServer/handlers");
ConfigurationElementCollection handlersCollection = handlersSection.GetCollection();
ConfigurationElement addElement = handlersCollection.CreateElement("add");
addElement["name"] = @"PHP-FastCGI";
addElement["path"] = @"*.php";
addElement["verb"] = @"GET,HEAD,POST";
addElement["modules"] = @"FastCgiModule";
addElement["scriptProcessor"] = @"c:\php\php-cgi.exe";
addElement["resourceType"] = @"Either";
handlersCollection.AddAt(0, addElement);
serverManager.CommitChanges();
}
}
}
VB.NET
Imports System
Imports System.Text
Imports Microsoft.Web.Administration
Module Sample
Sub Main()
Dim serverManager As ServerManager = New ServerManager
Dim appHostConfig As Configuration = serverManager.GetApplicationHostConfiguration
Dim fastCgiSection As ConfigurationSection = appHostConfig.GetSection("system.webServer/fastCgi")
Dim fastCgiCollection As ConfigurationElementCollection = fastCgiSection.GetCollection
Dim applicationElement As ConfigurationElement = fastCgiCollection.CreateElement("application")
applicationElement("fullPath") = "c:\php\php-cgi.exe"
fastCgiCollection.Add(applicationElement)
Dim webConfig As Configuration = serverManager.GetWebConfiguration("Contoso")
Dim handlersSection As ConfigurationSection = webConfig.GetSection("system.webServer/handlers")
Dim handlersCollection As ConfigurationElementCollection = handlersSection.GetCollection
Dim addElement As ConfigurationElement = handlersCollection.CreateElement("add")
addElement("name") = "PHP-FastCGI"
addElement("path") = "*.php"
addElement("verb") = "GET,HEAD,POST"
addElement("modules") = "FastCgiModule"
addElement("scriptProcessor") = "c:\php\php-cgi.exe"
addElement("resourceType") = "Either"
handlersCollection.AddAt(0, addElement)
serverManager.CommitChanges()
End Sub
End Module
JavaScript
var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var fastCgiSection = adminManager.GetAdminSection("system.webServer/fastCgi", "MACHINE/WEBROOT/APPHOST");
var fastCgiCollection = fastCgiSection.Collection;
var applicationElement = fastCgiCollection.CreateNewElement("application");
applicationElement.Properties.Item("fullPath").Value = "c:\\php\\php-cgi.exe";
fastCgiCollection.AddElement(applicationElement);
adminManager.CommitChanges();
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso";
var handlersSection = adminManager.GetAdminSection("system.webServer/handlers", "MACHINE/WEBROOT/APPHOST/Contoso");
var handlersCollection = handlersSection.Collection;
var addElement = handlersCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "PHP-FastCGI";
addElement.Properties.Item("path").Value = "*.php";
addElement.Properties.Item("verb").Value = "GET,HEAD,POST";
addElement.Properties.Item("modules").Value = "FastCgiModule";
addElement.Properties.Item("scriptProcessor").Value = "c:\\php\\php-cgi.exe";
addElement.Properties.Item("resourceType").Value = "Either";
handlersCollection.AddElement(addElement, 0);
adminManager.CommitChanges();
VBScript
Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set fastCgiSection = adminManager.GetAdminSection("system.webServer/fastCgi", "MACHINE/WEBROOT/APPHOST")
Set fastCgiCollection = fastCgiSection.Collection
Set applicationElement = fastCgiCollection.CreateNewElement("application")
applicationElement.Properties.Item("fullPath").Value = "c:\php\php-cgi.exe"
fastCgiCollection.AddElement applicationElement
adminManager.CommitChanges()
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso"
Set handlersSection = adminManager.GetAdminSection("system.webServer/handlers", "MACHINE/WEBROOT/APPHOST/Contoso")
Set handlersCollection = handlersSection.Collection
Set addElement = handlersCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "PHP-FastCGI"
addElement.Properties.Item("path").Value = "*.php"
addElement.Properties.Item("verb").Value = "GET,HEAD,POST"
addElement.Properties.Item("modules").Value = "FastCgiModule"
addElement.Properties.Item("scriptProcessor").Value = "c:\php\php-cgi.exe"
addElement.Properties.Item("resourceType").Value = "Either"
handlersCollection.AddElement addElement, 0
adminManager.CommitChanges()