Interfaccia IHttpModuleContextContainer

Articolo
07/10/2024

Gestisce una raccolta di puntatori IHttpStoredContext .

Sintassi

class IHttpModuleContextContainer

Metodi

Nella tabella seguente sono elencati i metodi esposti dalla IHttpModuleContextContainer classe .

Nome	Descrizione
GetModuleContext	Restituisce il contesto archiviato dal contenitore di contesto.
SetModuleContext	Imposta il contesto archiviato nel contenitore di contesto.

Classi derivate

Nome	Descrizione
IDispensedHttpModuleContextContainer	Estende `IHttpModuleContextContainer` fornendo funzionalità per il rilascio di un contenitore.

Osservazioni:

Molte classi IIS 7 mantengono un private IDispensedHttpModuleContextContainer puntatore come variabile membro. Queste classi implementano varie interfacce, tra cui IHttpApplication, IHttpConnection, IHttpContext, IHttpFileInfo, IHttpSite, IHttpUrlInfo e IMetadataInfo.

Ognuna di queste interfacce definisce un GetModuleContextContainer metodo, che non accetta argomenti e restituisce un IHttpModuleContextContainer puntatore. Quando vengono chiamati i vari GetModuleContextContainer metodi, la maggior parte di questi implementatori restituisce i private dati come upcast IHttpModuleContextContainer. Ciò consente agli implementatori dell'interfaccia di esporre contenitori personalizzati mantenendo al tempo stesso la durata di tali contenitori.

È possibile definire classi personalizzate che implementano l'interfaccia IHttpStoredContext e quindi creare un puntatore a questo IHttpStoredContext implementatore di classe chiamando l'operatore new . È quindi possibile aggiungere e recuperare questo puntatore in un IHttpModuleContextContainer puntatore chiamando rispettivamente i metodi SetModuleContext e GetModuleContext .

Quando il IHttpStoredContext puntatore non è più necessario, il metodo IHttpStoredContext::CleanupStoredContext viene chiamato internamente, dove l'implementatore del IHttpStoredContext metodo di interfaccia deve in genere chiamare delete``this.

Attenzione

Anche se può essere un'operazione sicura per eseguire il downcast di un IHttpModuleContextContainer oggetto a un IDispensedHttpModuleContextContainer usando l'operatore dynamic_cast , è consigliabile evitare di eseguire questo cast. L'interfaccia IDispensedHttpModuleContextContainer aggiunge un solo metodo, ReleaseContainer, alla relativa interfaccia di base e questo metodo deve essere chiamato solo internamente.

Note per i chiamanti

In alcuni casi, un IHttpModuleContextContainer puntatore può essere sottoposto a downcast in un'interfaccia IDispensedHttpModuleContextContainer per accedere al comportamento esteso.

Attenzione

Prima di eseguire qualsiasi operazione downcast, verificare sempre che il cast sia corretto per garantire il comportamento corretto del programma.

Nota

Quando possibile, è consigliabile usare l'operatore dynamic_cast quando si esegue un'operazione downcast.

Esempio

Nell'esempio di codice seguente viene illustrato come creare un modulo globale in ascolto degli eventi GL_TRACE_EVENT e quindi scrivere informazioni IHttpStoredContext personalizzate nel Visualizzatore eventi.

Attenzione

IIS 7 genera un numero elevato di eventi nel Visualizzatore eventi. Per evitare un errore di overflow del log in un ambiente di produzione, in genere è consigliabile evitare di scrivere informazioni sulla cache nel registro eventi. A scopo dimostrativo, questo esempio di codice scrive una voce nel Visualizzatore eventi solo in modalità di debug.

#pragma warning( disable : 4290 )
#pragma warning( disable : 4530 )

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <tchar.h>
#include <initguid.h>
#include <httptrace.h>
#include <httpserv.h>
#include <httpcach.h>

#include <string>
using namespace std;

// The CConvert class mirrors the Convert class that is 
// defined in the .NET Framework. It converts primitives 
// and other data types to wstring types.
class CConvert
{
public:
    // The ToByteString converts a double-byte 
    // character string to a single-byte string.
    // str: the double-byte string to convert.
    // return: a single-byte string copied from str.
    static string ToByteString(const wstring& str)
    {
        // Get the length of the 
        // double-byte string.
        size_t length = str.length();

        // Create a temporary char pointer.
        char* byteChar = new char[length+1];
        byteChar[0] = '\0';
        // Copy the double-byte character string
        // into the single-byte string.        
        size_t charsReturned = 0;
        wcstombs_s(&charsReturned, byteChar, 
                   length+1, str.c_str(), length+1);
        // Create a string to return.
        string retString = byteChar;
        // Delete the temporary string and
        // set that string to NULL.
        delete[] byteChar;
        byteChar = NULL;

        // Return the single-byte string.
        return retString;
    }
};

// The CEventWriter class writes XML 
// documents and strings to the event log.
class CEventWriter
{
public:
    // Creates the CEventWriter class.
    // name: the name of the 
    // event log to open.
    CEventWriter(const wstring& name)
    {                
        #ifdef UNICODE
        m_eventLog = RegisterEventSource(NULL, name.c_str());
        #else
        string multiName = CConvert::ToByteString(name);
        m_eventLog = RegisterEventSource(NULL, multiName.c_str());
        #endif        
    }

    // Creates the destructor for the 
    // CEventWriter class. This destructor
    // closes the HANDLE to the event 
    // log if that HANDLE is open.
    virtual ~CEventWriter()
    {
        // If the HANDLE to the event 
        // log is open, close it.
        if (NULL != m_eventLog)
        {
            // Deregister the event log HANDLE.
            DeregisterEventSource(m_eventLog);
            // Set the HANDLE to NULL.
            m_eventLog = NULL;
        }
    }

    // The ReportInfo method writes 
    // a wstring to the event log.
    // info: the wstring to write.
    // return: true if the event log is written.
    BOOL ReportInfo(const wstring& info)
    {
        return ReportEvent(EVENTLOG_INFORMATION_TYPE, info);
    }
protected:
    // The ReportEvent method accepts an event type
    // and a wstring, and attempts to write that 
    // event to the event log.
    // type: the type of the event.
    // data: the wstring to write to the event log.
    // return: true if the event log is written;
    // otherwise, false.
    BOOL ReportEvent(WORD type, const wstring& data)
    {
        // If the m_eventLog HANDLE 
        // is NULL, return false.
        if (NULL == m_eventLog)
        {
            return FALSE;
        }

        #ifndef _DEBUG
        // If the current build is not debug,
        // return so the event log is not written.
        return TRUE;
        #endif

        #ifdef UNICODE
        // The unicode version of the ReportEvent
        // method requires double-byte strings.
        PCWSTR arr[1];
        arr[0] = data.c_str();
        return ::ReportEvent(m_eventLog,
                             type,
                             0, 0, NULL, 1, 
                             0, arr, (void*)arr);
        #else
        // The non-unicode version of the ReportEvent
        // method requires single-byte strings.
        string multiByte = 
            CConvert::ToByteString(data);
        LPCSTR arr[1];
        arr[0] = multiByte.c_str();
        return ::ReportEvent(m_eventLog,
                             type,
                             0, 0, NULL, 1,
                             0, arr, (void*)arr);
        #endif
    }
private:
    // Specify the HANDLE to the 
    // event log for writing.
    HANDLE m_eventLog;
};

// The CStoredContext class implements 
// the IHttpStoredContext interface.
class CStoredContext : public IHttpStoredContext
{
public:
    // The constructor for the CStoredContext 
    // class. Initializes a CEventWriter to write
    // to the Event Log.
    CStoredContext() : m_eventWriter(L"IISADMIN")
    {
        // Create a string to write.
        wstring constructor(L"CStoredContext::Constructor");
        // Write the string to the Event Log.
        m_eventWriter.ReportInfo(constructor);
    }

    // The Display method writes 
    // L"CStoredContext::Display"
    // to the Event Log.
    virtual void Display()
    {
        // Create the string to write.
        wstring display(L"CStoredContext::Display");
        // Write the string to the Event Log.
        m_eventWriter.ReportInfo(display);
    }

    // The CleanupStoredContext is the pure virtual
    // method that all non-abstract classes implementing 
    // the IHttpStoredContext must implement.
    virtual void CleanupStoredContext()
    {        
        wstring cleanup(L"CStoredContext::CleanupStoredContext");
        m_eventWriter.ReportInfo(cleanup);
        delete this;
    }
protected:
    // The protected destructor for the 
    // CStoredContext class. This method is 
    // protected because the clients of this 
    // class should dispose of a class instance
    // by calling the CleanupStoredContext method.
    virtual ~CStoredContext()
    {
        wstring destructor(L"CStoredContext::Destructor");
        m_eventWriter.ReportInfo(destructor);
    }
private:    
    // Specify the private CEventWriter
    // for writing events.
    CEventWriter m_eventWriter;
};

// The CGlobalTraceModule class creates the CGlobalModule 
// class and registers for GL_TRACE_EVENT events.
class CGlobalContainerModule : public CGlobalModule
{
public:
    // Creates the destructor for the 
    // CGlobalTraceModule class.
    virtual ~CGlobalContainerModule()
    {

    }
    
    // The RegisterGlobalModule method creates and registers 
    // a new CGlobalTraceModule for GL_TRACE_EVENT events.
    // dwServerVersion: the current server version.
    // pModuleInfo: the current IHttpModuleRegistrationInfo pointer.
    // pGlobalInfo: the current IHttpServer pointer.
    // return: ERROR_NOT_ENOUGH_MEMORY if the heap is out of 
    // memory; otherwise, the value from the call to the 
    // SetGlobalNotifications method on the pModuleInfo pointer.
    static HRESULT RegisterGlobalModule
    (
        DWORD dwServerVersion,
        IHttpModuleRegistrationInfo* pModuleInfo,
        IHttpServer* pGlobalInfo
    )
    {        
        // The IHttpModuleRegistrationInfo 
        // pointermust not be NULL.
        if (NULL == pModuleInfo)
        {
            return E_INVALIDARG;
        }

        // Get the HTTP_MODULE_ID from the 
        // IHttpModuleRegistrationInfo pointer.
        HTTP_MODULE_ID moduleId = 
            pModuleInfo->GetId();

        // The HTTP_MODULE_ID pointer 
        // must not be NULL.
        if (NULL == moduleId)
        {
            return E_INVALIDARG;
        }

        // Create a new CGlobalContainerModule pointer
        // using the HTTP_MODULE_ID from the 
        // IHttpModuleRegistrationInfo pointer.
        CGlobalContainerModule* containerModule = 
            new CGlobalContainerModule(moduleId);

        // Return an out-of-memory error if the containerModule 
        // is NULL after the call to the new operator.
        if (NULL == containerModule)
        {            
            return HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY);
        }                                          

        // Attempt to set global notification 
        // for an GL_TRACE_EVENT event by using 
        // the traceModule as a listener.
        HRESULT hr = pModuleInfo->SetGlobalNotifications
            (containerModule, GL_TRACE_EVENT);

        // Return the HRESULT from the call to 
        // the SetGlobalNotifications method.        
        return hr;
    }
    
    // The OnGlobalTraceEvent method is the callback
    // method for GL_TRACE_EVENT events in the pipeline.
    // pProvider: the IGlobalTraceEventProvider pointer.
    // return: GL_NOTIFICATION_CONTINUE.
    virtual 
    GLOBAL_NOTIFICATION_STATUS
    OnGlobalTraceEvent
    (
        IN IGlobalTraceEventProvider* pProvider
    )
    {
        // If the IGlobalTraceEventProvider pointer 
        // is NULL, return GL_NOTIFICATION_CONTINUE.
        if (NULL == pProvider)
        {
            return GL_NOTIFICATION_CONTINUE;
        }

        // Declare an IHttpContext pointer.
        IHttpContext* httpContext = NULL;

        // Declare an HRESULT and initialize
        // the HRESULT to E_FAIL.
        HRESULT hr = E_FAIL;

        // Call the GetCurrentHttpRequestContext
        // method on the IGlobalTraceEventProvider
        // pointer.
        hr = pProvider->GetCurrentHttpRequestContext(&httpContext);

        // If the GetCurrentHttpRequestContext 
        // method failed, or the IHttpContext
        // pointer is NULL, return GL_NOTIFICATION_CONTINUE.
        if (FAILED(hr) || (NULL == httpContext))
        {
            return GL_NOTIFICATION_CONTINUE;
        }

        // Get the IHttpModuleContextContainer
        // pointer from the IHttpContext pointer.
        IHttpModuleContextContainer* container =
            httpContext->GetModuleContextContainer();

        // If the IHttpModuleContextContainer is 
        // NULL, return GL_NOTIFICATION_CONTINUE.
        if (NULL == container)
        {
            return GL_NOTIFICATION_CONTINUE;
        }

        // Get the IHttpStoredContext pointer 
        // from the IHttpModuleContextContainer
        // pointer.
        IHttpStoredContext* storedContext =
            container->GetModuleContext(m_moduleId);

        // If the IHttpStoredContext pointer is
        // non-NULL, use the dynamic_cast operator
        // to retrieve the CStoredContext pointer
        // from the storedContext.
        if (NULL != storedContext)
        {                
            // Attempt to cast the IHttpStoredContext
            // pointer to a CStoredContext pointer.
            CStoredContext* customContext =
                dynamic_cast<CStoredContext*>(storedContext);

            // If the cast does not return 
            // NULL, ask the CStoredContext 
            // poitner to display itself.
            if (NULL != customContext)
            {
                customContext->Display();
            }
        }
        if (NULL == storedContext)
        {
            // Create a custom CStoredContext pointer.
            IHttpStoredContext* customContext =
                new CStoredContext;
            // Call the SetModuleContext method using 
            // the IHttpModuleContextContainer pointer.
            container->SetModuleContext(customContext, m_moduleId);
        }
        
        // Return GL_NOTIFICATION_CONTINUE.
        return GL_NOTIFICATION_CONTINUE;
    }

    // The Terminate method is required for
    // non-abstract CGlobalTraceModule classes.
    // This method calls delete on this.
    virtual VOID Terminate(VOID)
    {
        delete this;
    }
protected:
    // Creates the constructor for the CGlobalTraceModule 
    // class. This constructor initializes the CEventWriter
    // to write to the application event log.
    // moduleId: the current module identifier.
    CGlobalContainerModule(HTTP_MODULE_ID moduleId)        
    {
        m_moduleId = moduleId;
    }
private:
    // Specify the HTTP_MODULE_ID
    // for this module.
    HTTP_MODULE_ID m_moduleId;
};

// The RegisterModule method is the 
// main entry point for the DLL.
// dwServerVersion: the current server version.
// pModuleInfo: the current 
// IHttpModuleRegistrationInfo pointer.
// pGlobalInfo: the current IHttpServer pointer.
// return: the value returned by calling the
// CGlobalContainerModule::RegisterGlobalModule
// method.
HRESULT
__stdcall
RegisterModule(
    DWORD dwServerVersion,
    IHttpModuleRegistrationInfo* pModuleInfo,
    IHttpServer* pGlobalInfo
)
{        
    // Call the static method for initialization.
    return CGlobalContainerModule::RegisterGlobalModule            
        (dwServerVersion, 
         pModuleInfo, 
         pGlobalInfo);             
}

Il codice precedente scrive un nuovo evento nella Visualizzatore eventi, in cui la casella Dati contiene stringhe consecutive simili alle seguenti.

CStoredContext::Destructor

CStoredContext::CleanupStoredContext

CStoredContext::Display

CStoredContext::Constructor

Il modulo deve esportare la funzione RegisterModule . È possibile esportare questa funzione creando un file di definizione del modulo (con estensione def) per il progetto oppure è possibile compilare il modulo usando l'opzione /EXPORT:RegisterModule . Per altre informazioni, vedere Procedura dettagliata: Creazione di un modulo HTTP a livello di richiesta tramite codice nativo.

Facoltativamente, è possibile compilare il codice usando la __stdcall (/Gz) convenzione di chiamata anziché dichiarare in modo esplicito la convenzione di chiamata per ogni funzione.

Gerarchia di ereditarietà

IHttpModuleContextContainer

IDispensedHttpModuleContextContainer

Requisiti

Tipo	Descrizione
Client	- IIS 7.0 in Windows Vista - IIS 7.5 in Windows 7 - IIS 8.0 in Windows 8 - IIS 10.0 in Windows 10
Server	- IIS 7.0 in Windows Server 2008 - IIS 7.5 in Windows Server 2008 R2 - IIS 8.0 in Windows Server 2012 - IIS 8.5 in Windows Server 2012 R2 - IIS 10.0 in Windows Server 2016
Prodotto	- IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0 - IIS Express 7.5, IIS Express 8.0, IIS Express 10.0
Intestazione	Httpserv.h

Vedi anche

Interfacce Web Server Core

Condividi tramite

Interfaccia IHttpModuleContextContainer

Sintassi

Metodi

Classi derivate

Osservazioni:

Note per i chiamanti

Esempio

Gerarchia di ereditarietà

Requisiti

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive