Procédure pas à pas : création d’un module HTTP Global-Level à l’aide de code natif

Article
07/19/2023

Cette procédure pas à pas montre comment utiliser C++ pour créer un exemple de module HTTP de niveau global qui implémente la nouvelle architecture de traitement des demandes dans IIS 7. Cette nouvelle architecture étend les fonctionnalités de programmation de code natif lorsque vous écrivez des applications IIS sur des versions antérieures de modules HTTP ASP.NET et de filtres ou d’extensions ISAPI. Pour plus d’informations sur la conception de modules HTTP à l’aide de la nouvelle architecture de traitement des requêtes, consultez Conception de modules HTTP Native-Code.

Dans cette procédure pas à pas, vous allez créer un projet C++ pour votre module HTTP, ajouter le code requis pour un projet « Hello World », puis compiler et tester le module.

Prérequis

Le logiciel suivant est requis pour effectuer les étapes de l’exemple :

IIS 7.
Visual Studio 2005 :

Notes

Vous pouvez également utiliser Visual Studio .NET 2003 ou une version antérieure, bien que les étapes pas à pas ne soient pas identiques.

Création du module

Dans cette partie de la procédure pas à pas, vous allez créer un projet de DLL C++ vide pour votre module HTTP.

Pour créer un projet DLL C++

Démarrez Visual Studio 2005.
Vérifiez que les options globales ont tous les chemins d’accès appropriés aux fichiers include du KIT de développement logiciel (SDK) :
1. Dans le menu Outils , cliquez sur Options.
2. Développez le nœud Projets et solutions dans l’arborescence, puis cliquez sur Vc++ Répertoires.
3. Dans la zone de liste déroulante Afficher les répertoires pour , sélectionnez Inclure les fichiers.
4. Vérifiez que le chemin d’accès où vous avez installé les fichiers include du KIT de développement logiciel (SDK) est répertorié. Si le chemin d’accès n’est pas répertorié, cliquez sur l’icône Nouvelle ligne , puis ajoutez le chemin d’accès où vous avez installé les fichiers include du Kit de développement logiciel (SDK).
5. Cliquez sur OK.
Créez un projet C++ :
1. Dans le menu Fichier , pointez sur Nouveau, puis cliquez sur Projet.
  
  La boîte de dialogue Nouveau projet s’affiche.
2. Dans le volet Types de projets , développez le nœud Visual C++ , puis cliquez sur Win32.
3. Dans le volet Modèles , sélectionnez Projet Win32.
4. Dans la zone Nom , tapez HelloWorld.
5. Dans la zone Emplacement , tapez le chemin d’accès de l’exemple.
6. Cliquez sur OK.
  
  L’Assistant Application Win32 s’ouvre.
7. Cliquez sur Paramètres de l’application.
8. Sous Type d’application, cliquez sur DLL.
9. Sous Options supplémentaires, cliquez sur Projet vide.
10. Cliquez sur Terminer.

Ajout du code et des fichiers sources

L’étape suivante consiste à ajouter les fichiers de définition de module et C++ requis au projet.

Pour ajouter les fichiers sources au projet

Créez le fichier de définition de module pour exporter la fonction RegisterModule :
1. Dans Explorateur de solutions, cliquez avec le bouton droit sur Fichiers sources, pointez sur Ajouter, puis cliquez sur Nouvel élément.
  
  La boîte de dialogue Ajouter un nouvel élément s’ouvre.
2. Développez le nœud Visual C++ dans le volet Catégories , puis cliquez sur Code.
3. Dans le volet Modèles , sélectionnez le modèle Fichier de définition de module .
4. Dans la zone Nom , tapez HelloWorld et laissez le chemin d’accès par défaut du fichier dans la zone Emplacement .
5. Cliquez sur Add.
6. Ajoutez le code suivant :
```
LIBRARY HelloWorld  

EXPORTS  
    RegisterModule  
```
Vous pouvez éventuellement exporter la fonction RegisterModule à l’aide du commutateur /EXPORT:RegisterModule :
1. Dans le menu Projet , cliquez sur Propriétés HelloWorld.
2. Développez le nœud Propriétés de configuration dans l’arborescence, développez le nœud Éditeur de liens, puis cliquez sur Ligne de commande.
3. Dans la zone de liste déroulante Configuration , sélectionnez Toutes les configurations.
4. Dans la zone Options supplémentaires , tapez /EXPORT:RegisterModule.
5. Cliquez sur OK.

Créez le fichier C++ :

Dans Explorateur de solutions, cliquez avec le bouton droit sur Fichiers sources, pointez sur Ajouter, puis cliquez sur Nouvel élément.

La boîte de dialogue Ajouter un nouvel élément s’ouvre.
Développez le nœud Visual C++ dans le volet Catégories , puis cliquez sur Code.
Dans le volet Modèles , sélectionnez le modèle Fichier C++ .
Dans la zone Nom , tapez HelloWorld et laissez le chemin d’accès par défaut du fichier dans la zone Emplacement .
Cliquez sur Add.

Ajoutez le code suivant :

#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 );
}

Vous pouvez éventuellement compiler le code à l’aide de la convention d’appel __stdcall (/Gz) :
1. Dans le menu Projet , cliquez sur Propriétés HelloWorld.
2. Développez le nœud Propriétés de configuration dans l’arborescence, développez le nœud C/C++ , puis cliquez sur Avancé.
3. Dans la zone de liste déroulante Configuration , sélectionnez Toutes les configurations.
4. Dans la zone de liste déroulante Convention d’appel , sélectionnez __stdcall (/Gz).
5. Cliquez sur OK.

Compilation et test du module

Votre module HTTP a tout ce dont il a besoin. Il suffit de compiler et de tester votre module HTTP.

Pour compiler et tester le projet

Compilez le module HTTP :
1. Dans le menu Générer, cliquez sur Générer la solution.
2. Vérifiez que Visual Studio n’a pas retourné d’erreurs ou d’avertissements. Si vous rencontrez des erreurs ou des avertissements, vous devez résoudre ces problèmes avant de tester le projet.
Copiez le fichier DLL du module HTTP dans votre dossier IIS :
1. Ouvrez Windows Explorer et recherchez le dossier par défaut spécifié lors de la création du projet C++.
  
  Selon vos options de build, vous devez voir un dossier nommé Debug ou Release dans le dossier par défaut de votre projet.
2. Dans le dossier Débogage ou Release, recherchez le fichier nommé HelloWorld.dll.
3. Copiez le fichier HelloWorld.dll dans votre dossier Inetsrv, qui se trouve par défaut dans %WinDir%\System32\Inetsrv.
Ajoutez le module HelloWorld.dll à votre liste de modules (pour obtenir des instructions, consultez Conception de modules HTTP Native-Code).
Utilisez Internet Explorer pour accéder à votre site Web. Vous devez voir le contenu de votre site Web normal.
Ouvrez le observateur d'événements Windows et basculez vers le journal global des applications . Vous devez voir une entrée qui répertorie « IISADMIN » comme source d’événement.
Cliquez avec le bouton droit sur l’événement, puis cliquez sur Propriétés pour afficher les détails de l’événement. Un message « Hello World ! » doit s’afficher dans le volet Description.

Résolution des problèmes liés à vos paramètres

Si votre module ne se compile pas ou ne fonctionne pas comme prévu, voici plusieurs domaines que vous pouvez case activée :

Vérifiez que vous avez spécifié __stdcall pour vos fonctions exportées ou que vous avez configuré la compilation à l’aide de la convention d’appel __stdcall (/Gz) .
Vérifiez que vous avez ajouté l’exportation correcte RegisterModule à votre fichier de définition.
Vérifiez que vous avez ajouté le fichier de définition aux paramètres du projet. Pour ajouter le fichier aux paramètres du projet, procédez comme suit :
1. Dans le menu Projet , cliquez sur Propriétés.
2. Développez le nœud Propriétés de configuration dans l’arborescence, développez le nœud Éditeur de liens, puis cliquez sur Entrée.
3. Pour les paramètres Fichier de définition de module , vérifiez que votre fichier de définition est répertorié.

Partager via