Exemplarische Vorgehensweise: Erstellen eines Global-Level HTTP-Moduls mithilfe von nativem Code

Artikel
07/19/2023

In dieser exemplarischen Vorgehensweise wird veranschaulicht, wie Sie mit C++ ein HTTP-Beispielmodul auf globaler Ebene erstellen, das die neue Anforderungsverarbeitungsarchitektur in IIS 7 implementiert. Diese neue Architektur erweitert die Funktionen der nativen Codeprogrammierung, wenn Sie IIS-Anwendungen über frühere Versionen von ASP.NET HTTP-Modulen und ISAPI-Filtern oder -Erweiterungen schreiben. Weitere Informationen zum Entwerfen von HTTP-Modulen mithilfe der neuen Anforderungsverarbeitungsarchitektur finden Sie unter Entwerfen Native-Code HTTP-Module.

In dieser exemplarischen Vorgehensweise erstellen Sie ein C++-Projekt für Ihr HTTP-Modul, fügen den erforderlichen Code für ein "Hallo Welt"-Projekt hinzu und kompilieren und testen dann das Modul.

Voraussetzungen

Die folgende Software ist erforderlich, um die Schritte im Beispiel auszuführen:

IIS 7.
Visual Studio 2005.

Hinweis

Sie können auch Visual Studio .NET 2003 oder früher verwenden, obwohl die Schritte zur exemplarischen Vorgehensweise möglicherweise nicht identisch sind.

Erstellen des Moduls

In diesem Teil der exemplarischen Vorgehensweise erstellen Sie ein leeres C++-DLL-Projekt für Ihr HTTP-Modul.

So erstellen Sie ein neues C++-DLL-Projekt

Starten Sie Visual Studio 2005.
Vergewissern Sie sich, dass die globalen Optionen alle richtigen Pfade zum SDK enthalten:
1. Klicken Sie im Menü Extras auf Optionen.
2. Erweitern Sie den Knoten Projekte und Projektmappen in der Strukturansicht, und klicken Sie dann auf VC++-Verzeichnisse.
3. Wählen Sie im Dropdownfeld Verzeichnisse für anzeigen die Option Dateien einschließen aus.
4. Vergewissern Sie sich, dass der Pfad aufgeführt ist, in dem Sie die SDK-Includedateien installiert haben. Wenn der Pfad nicht aufgeführt ist, klicken Sie auf das Symbol Neue Zeile , und fügen Sie dann den Pfad hinzu, in dem Sie die SDK-Includedateien installiert haben.
5. Klicken Sie auf OK.
Erstellen Sie ein neues C++-Projekt:
1. Zeigen Sie im Menü Datei auf Neu, und klicken Sie dann auf Projekt.
  
  Das Dialogfeld Neues Projekt wird angezeigt.
2. Erweitern Sie im Bereich Projekttypen den Knoten Visual C++ , und klicken Sie dann auf Win32.
3. Wählen Sie im Bereich Vorlagendie Option Win32-Projekt aus.
4. Geben Sie im Feld Nameden Namen HelloWorld ein.
5. Geben Sie im Feld Speicherort den Pfad für das Beispiel ein.
6. Klicken Sie auf OK.
  
  Der Win32-Anwendungs-Assistent wird geöffnet.
7. Klicken Sie auf Anwendungseinstellungen.
8. Klicken Sie unter Anwendungstyp auf DLL.
9. Klicken Sie unter Zusätzliche Optionen auf Leeres Projekt.
10. Klicken Sie auf Fertig stellen.

Hinzufügen des Codes und der Quelldateien

Der nächste Schritt besteht darin, dem Projekt die erforderlichen C++- und Moduldefinitionsdateien hinzuzufügen.

So fügen Sie dem Projekt die Quelldateien hinzu

Erstellen Sie die Moduldefinitionsdatei, um die Funktion RegisterModule zu exportieren:
1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf Quelldateien, zeigen Sie auf Hinzufügen, und klicken Sie dann auf Neues Element.
  
  Das Dialogfeld Neues Element hinzufügen wird angezeigt.
2. Erweitern Sie den Knoten Visual C++ im Bereich Kategorien , und klicken Sie dann auf Code.
3. Wählen Sie im Bereich Vorlagen die Vorlage Moduldefinitionsdatei aus.
4. Geben Sie im Feld Nameden Namen HelloWorld ein, und behalten Sie den Standardpfad für die Datei im Feld Speicherort bei.
5. Klicken Sie auf Hinzufügen.
6. Fügen Sie den folgenden Code hinzu:
```
LIBRARY HelloWorld  

EXPORTS  
    RegisterModule  
```
Optional können Sie die RegisterModule-Funktion mithilfe des Schalters /EXPORT:RegisterModule exportieren:
1. Klicken Sie im Menü Projekt auf HelloWorld-Eigenschaften.
2. Erweitern Sie den Knoten Konfigurationseigenschaften in der Strukturansicht, erweitern Sie den Knoten Linker , und klicken Sie dann auf Befehlszeile.
3. Wählen Sie im Dropdownfeld Konfigurationdie Option Alle Konfigurationen aus.
4. Geben Sie im Feld Zusätzliche Optionenden Namen /EXPORT:RegisterModule ein.
5. Klicken Sie auf OK.

Erstellen Sie die C++-Datei:

Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf Quelldateien, zeigen Sie auf Hinzufügen, und klicken Sie dann auf Neues Element.

Das Dialogfeld Neues Element hinzufügen wird angezeigt.
Erweitern Sie den Knoten Visual C++ im Bereich Kategorien , und klicken Sie dann auf Code.
Wählen Sie im Bereich Vorlagen die Vorlage C++-Datei aus.
Geben Sie im Feld Nameden Namen HelloWorld ein, und behalten Sie den Standardpfad für die Datei im Feld Speicherort bei.
Klicken Sie auf Hinzufügen.

Fügen Sie den folgenden Code hinzu:

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <httpserv.h>

// Create the module's global class.
class MyGlobalModule : public CGlobalModule
{
public:

    // Process a GL_APPLICATION_START notification.
    GLOBAL_NOTIFICATION_STATUS
    OnGlobalPreBeginRequest(
        IN IPreBeginRequestProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );
        WriteEventViewerLog( "Hello World!" );
        return GL_NOTIFICATION_CONTINUE;
    }

    VOID Terminate()
    {
        // Remove the class from memory.
        delete this;
    }

    MyGlobalModule()
    {
        // Open a handle to the Event Viewer.
        m_hEventLog = RegisterEventSource( NULL,"IISADMIN" );
    }

    ~MyGlobalModule()
    {
        // Test whether the handle for the Event Viewer is open.
        if (NULL != m_hEventLog)
        {
            // Close the handle to the Event Viewer.
            DeregisterEventSource( m_hEventLog );
            m_hEventLog = NULL;
        }
    }

private:

    // Create a handle for the event viewer.
    HANDLE m_hEventLog;

    // Define a method that writes to the Event Viewer.
    BOOL WriteEventViewerLog(LPCSTR szNotification)
    {
        // Test whether the handle for the Event Viewer is open.
        if (NULL != m_hEventLog)
        {
            // Write any strings to the Event Viewer and return.
            return ReportEvent(
                m_hEventLog,
                EVENTLOG_INFORMATION_TYPE, 0, 0,
                NULL, 1, 0, &szNotification, NULL );
        }
        return FALSE;
    }
};

// Create the module's exported registration function.
HRESULT
__stdcall
RegisterModule(
    DWORD dwServerVersion,
    IHttpModuleRegistrationInfo * pModuleInfo,
    IHttpServer * pGlobalInfo
)
{
    UNREFERENCED_PARAMETER( dwServerVersion );
    UNREFERENCED_PARAMETER( pGlobalInfo );

    // Create an instance of the global module class.
    MyGlobalModule * pGlobalModule = new MyGlobalModule;
    // Test for an error.
    if (NULL == pGlobalModule)
    {
        return HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY);
    }
    // Set the global notifications and exit.
    return pModuleInfo->SetGlobalNotifications(
        pGlobalModule, GL_PRE_BEGIN_REQUEST );
}

Sie können den Code optional mithilfe der __stdcall (/Gz) aufrufenden Konvention kompilieren:
1. Klicken Sie im Menü Projekt auf HelloWorld-Eigenschaften.
2. Erweitern Sie den Knoten Konfigurationseigenschaften in der Strukturansicht, erweitern Sie den Knoten C/C++ , und klicken Sie dann auf Erweitert.
3. Wählen Sie im Dropdownfeld Konfigurationdie Option Alle Konfigurationen aus.
4. Wählen Sie im Dropdownfeld Anrufkonventiondie Option __stdcall (/Gz)aus.
5. Klicken Sie auf OK.

Kompilieren und Testen des Moduls

Ihr HTTP-Modul verfügt über alles, was es benötigt. Alles, was erforderlich ist, ist, ihr HTTP-Modul zu kompilieren und zu testen.

So kompilieren und testen Sie das Projekt

Kompilieren Sie das HTTP-Modul:
1. Klicken Sie im Menü Erstellen auf Projektmappe erstellen.
2. Stellen Sie sicher, dass Visual Studio keine Fehler oder Warnungen zurückgegeben hat. Wenn Fehler oder Warnungen auftreten, müssen Sie diese Probleme beheben, bevor Sie das Projekt testen.
Kopieren Sie die DLL-Datei für das HTTP-Modul in Ihren IIS-Ordner:
1. Öffnen Sie Windows Explorer, und suchen Sie den Standardordner, der beim Erstellen des C++-Projekts angegeben wurde.
  
  Abhängig von Ihren Buildoptionen sollte im Standardordner für Ihr Projekt ein Ordner mit dem Namen Debug oder Release angezeigt werden.
2. Suchen Sie im Ordner Debuggen oder Release nach der Datei mit dem Namen HelloWorld.dll.
3. Kopieren Sie die HelloWorld.dll-Datei in Ihren Ordner Inetsrv, der sich standardmäßig unter %WinDir%\System32\Inetsrv befindet.
Fügen Sie das modul HelloWorld.dll ihrer Modulliste hinzu (Anweisungen finden Sie unter Entwerfen Native-Code HTTP-Module).
Verwenden Sie internet Explorer, um zu Ihrer Website zu navigieren. Sie sollten Ihren normalen Websiteinhalt sehen.
Öffnen Sie die Windows-Ereignisanzeige, und wechseln Sie zum globalen Anwendungsprotokoll. Es sollte ein Eintrag angezeigt werden, in dem "IISADMIN" als Ereignisquelle aufgeführt wird.
Klicken Sie mit der rechten Maustaste auf das Ereignis, und klicken Sie dann auf Eigenschaften , um die Ereignisdetails anzuzeigen. Im Beschreibungsbereich sollte die Meldung "Hallo Welt!" angezeigt werden.

Problembehandlung für Ihre Einstellungen

Wenn Ihr Modul nicht kompiliert wird oder nicht wie erwartet funktioniert, können Sie die folgenden Bereiche überprüfen:

Stellen Sie sicher, dass Sie für Ihre exportierten Funktionen angegeben __stdcall oder die Kompilierung mithilfe der __stdcall (/Gz) Aufrufkonvention konfiguriert haben.
Stellen Sie sicher, dass Sie der Definitionsdatei den richtigen RegisterModule Export hinzugefügt haben.
Stellen Sie sicher, dass Sie die Definitionsdatei zu den Projekteinstellungen hinzugefügt haben. Führen Sie die folgenden Schritte aus, um die Datei zu den Projekteinstellungen hinzuzufügen:
1. Klicken Sie im Menü Projekt auf Eigenschaften.
2. Erweitern Sie den Knoten Konfigurationseigenschaften in der Strukturansicht, erweitern Sie den Knoten Linker , und klicken Sie dann auf Eingabe.
3. Stellen Sie für die Moduldefinitionsdateieinstellungen sicher, dass Ihre Definitionsdatei aufgeführt ist.

Freigeben über