Implémentation des interfaces d'assistance d'hôte intelligentImplementing Smart Host Helper Interfaces

L’interface IDebugDocumentHelper simplifie considérablement la tâche de création d’un hôte intelligent pour le débogage, car elle fournit des implémentations pour de nombreuses interfaces nécessaires pour l’hébergement intelligent.The IDebugDocumentHelper Interface interface greatly simplifies the task of creating a smart host for Active Debugging, because it provides implementations for many interfaces necessary for smart hosting.

Pour être un hôte intelligent utilisant IDebugDocumentHelper, une application hôte doit effectuer uniquement trois actions :To be a smart host using IDebugDocumentHelper, a host application must do only three things:

  1. CoCreate le gestionnaire de débogage de processus et utiliser l’interface IProcessDebugManager pour ajouter votre application à la liste des applications pouvant être déboguées.CoCreate the Process Debug Manager, and use the IProcessDebugManager Interface interface to add your application to the list of debuggable applications.

  2. Créer une assistance de document de débogage pour chaque objet de script, à l’aide de la méthode IProcessDebugManager::CreateDebugDocumentHelper.Create a debug document helper for each script object, using the IProcessDebugManager::CreateDebugDocumentHelper method. Vérifiez que le nom du document, le document parent, le texte et les blocs de script sont définis.Make sure that the document name, parent document, text, and script blocks are defined.

  3. Implémenter l’interface IActiveScriptSiteDebug sur l’objet qui implémente l’interface IActiveScriptSite (qui est nécessaire pour Active Scripting).Implement the IActiveScriptSiteDebug Interface interface on your object that implements the IActiveScriptSite interface (which is needed for Active Scripting). La seule méthode non triviale sur l’interface IActiveScriptSiteDebug délègue simplement à l’assistance.The only non-trivial method on the IActiveScriptSiteDebug interface simply delegates to the helper.

    Si vous le souhaitez, l’hôte peut implémenter l’interface IDebugDocumentHost s’il a besoin de mieux contrôler la couleur de la syntaxe, la création de contexte de document et d’autres fonctionnalités étendues.Optionally, the host can implement the IDebugDocumentHost Interface interface if it needs additional control over syntax color, document context creation, and other extended functionality.

    La principale limitation de l’assistance d’hôte intelligent est qu’elle ne peut traiter que les documents dont le contenu change ou diminue après leur ajout (bien que les documents puissent croître).The main limitation on the smart host helper is that it can only handle documents whose contents change or shrink after they have been added (although documents can expand). Pour de nombreux hôtes intelligents, toutefois, la fonctionnalité qu’elle fournit est exactement celle qui est nécessaire.For many smart hosts, however, the functionality it provides is exactly what is needed.

    Les sections suivantes décrivent chaque étape en détail.The following sections explain each step in more detail.

Créer un objet d’applicationCreate an Application Object

Avant de pouvoir utiliser l’assistance d’hôte intelligent, vous devez créer un objet d’interface IDebugApplication pour représenter votre application dans le débogueur.Before the smart host helper can be used, it is necessary to create an IDebugApplication Interface object to represent your application in the debugger.

Pour créer un objet d'applicationTo create an application object

  1. Créez une instance du gestionnaire de débogage de processus à l’aide de CoCreateInstance.Create an instance of the process debug manager using CoCreateInstance.

  2. Appelez IProcessDebugManager::CreateApplication.Call IProcessDebugManager::CreateApplication.

  3. Définissez le nom de l’application à l’aide de IDebugApplication::SetName.Set the name on the application by using IDebugApplication::SetName.

  4. Ajoutez l’objet d’application à la liste des applications pouvant être déboguées à l’aide de IProcessDebugManager::AddApplication.Add the application object to the list of debuggable applications by using IProcessDebugManager::AddApplication.

    Le code ci-dessous illustre le processus, mais il n’inclut pas de vérification des erreurs ou autres techniques de programmation robuste.The code below outlines the process, but it does not include error checking or other robust programming techniques.

    CoCreateInstance(CLSID_ProcessDebugManager, NULL,  
          CLSCTX_INPROC_SERVER | CLSCTX_INPROC_HANDLER  
          | CLSCTX_LOCAL_SERVER,  
    IID_IProcessDebugManager, (void **)&g_ppdm);  
    g_ppdm->CreateApplication(&g_pda);  
    g_pda->SetName(L"My cool application");  
    g_ppdm->AddApplication(g_pda, &g_dwAppCookie);  
    

Utilisation d’IDebugDocumentHelperUsing IDebugDocumentHelper

Pour utiliser l’assistance (séquence d’étapes minimale)To use the helper (minimal sequence of steps)

  1. Pour chaque document hôte, créez une assistance à l’aide de IProcessDebugManager::CreateDebugDocumentHelper.For each host document, create a helper using IProcessDebugManager::CreateDebugDocumentHelper.

  2. Appelez IDebugDocumentHelper::Init sur l’assistance, en donnant le nom, les attributs de document, et ainsi de suite.Call IDebugDocumentHelper::Init on the helper, giving the name, document attributes, and so on.

  3. Appelez IDebugDocumentHelper::Attach avec l’assistance parente pour le document (ou NULL si le document est la racine) afin de définir la position du document dans l’arborescence et le rendre visible par le débogueur.Call IDebugDocumentHelper::Attach with parent helper for the document (or NULL if the document is the root) to define the position of the document in the tree and make it visible to the debugger.

  4. Appelez IDebugDocumentHelper::AddDBCSText ou IDebugDocumentHelper::AddUnicodeText pour définir le texte du document.Call IDebugDocumentHelper::AddDBCSText or IDebugDocumentHelper::AddUnicodeText to define the text of the document. (Vous pouvez les appeler plusieurs fois si le document est téléchargé de façon incrémentielle, comme dans le cas d’un navigateur.)(These can be called multiple times if document is downloaded incrementally, as in the case of a browser.)

  5. Appelez IDebugDocumentHelper::DefineScriptBlock afin de définir les plages pour chaque bloc de script et les moteurs de script associés.Call IDebugDocumentHelper::DefineScriptBlock to define the ranges for each script block and the associated script engines.

Implémentation d’IActiveScriptSiteDebugImplementing IActiveScriptSiteDebug

Pour implémenter IActiveScriptSiteDebug::GetDocumentContextFromPosition, obtenez l’assistance correspondant au site en question, puis obtenez l’offset du document de départ pour le contexte source donné, comme suit :To implement IActiveScriptSiteDebug::GetDocumentContextFromPosition, get the helper corresponding to the given site, and then get the starting document offset for the given source context, as follows:

pddh->GetScriptBlockInfo(dwSourceContext, NULL, &ulStartPos, NULL);  

Ensuite, utilisez l’assistance pour créer un contexte de document pour l’offset de caractère donné :Next, use the helper to create a new document context for the given character offset:

pddh->CreateDebugDocumentContext(ulStartPos + uCharacterOffset, cChars, &pddcNew);  

Pour implémenter IActiveScriptSiteDebug::GetRootApplicationNode, appelez simplement IDebugApplication::GetRootNode (héritée de IRemoteDebugApplication::GetRootNode).To implement IActiveScriptSiteDebug::GetRootApplicationNode, simply call IDebugApplication::GetRootNode (inherited from IRemoteDebugApplication::GetRootNode).

Pour implémenter IDebugDocumentHelper::GetDebugApplicationNode, retournez simplement l’objet IDebugApplication que vous avez initialement créé à l’aide du gestionnaire de débogage de processus.To implement IDebugDocumentHelper::GetDebugApplicationNode, simply return the IDebugApplication you initially created using the process debug manager.

L’interface IDebugDocumentHost facultativeThe optional IDebugDocumentHost interface

L’hôte peut fournir une implémentation de l’interface IDebugDocumentHost à l’aide de IDebugDocumentHelper::SetDebugDocumentHost afin de bénéficier d’un contrôle supplémentaire sur l’assistance.The host can provide an implementation of the IDebugDocumentHost Interface by using IDebugDocumentHelper::SetDebugDocumentHost to give it additional control over the helper. L’interface hôte vous permet entre autres d’effectuer les tâches suivantes :Here are some of the key things the host interface allows you to do:

  • Ajouter du texte à l’aide de IDebugDocumentHelper::AddDeferredText pour que l’hôte n’ait pas besoin de fournir immédiatement les caractères.Add text using IDebugDocumentHelper::AddDeferredText so that the host does not need to provide the actual characters immediately. Quand ceux-ci sont réellement nécessaires, l’assistance appelle IDebugDocumentHost::GetDeferredText sur l’hôte.When the characters are really needed, the helper will call IDebugDocumentHost::GetDeferredText on the host.

  • Remplacer la coloration syntaxique par défaut fournie par l’assistance.Override the default syntax coloring provided by the helper. L’assistance appelle IDebugDocumentHost::GetScriptTextAttributes afin de déterminer la coloration pour une plage de caractères, et utilise son implémentation par défaut si l’hôte retourne E_NOTIMPL.The helper calls IDebugDocumentHost::GetScriptTextAttributes to determine the coloring for a range of characters, falling back on its default implementation if the host return E_NOTIMPL.

  • Fournir un contrôle inconnu pour les contextes de document créés par l’assistance en implémentant IDebugDocumentHost::OnCreateDocumentContext.Provide a controlling unknown for document contexts created by the helper by implementing IDebugDocumentHost::OnCreateDocumentContext. Cela permet à l’hôte de substituer la fonctionnalité de l’implémentation de contexte de document par défaut.This allows the host to override the functionality of the default document context implementation.

  • Fournir un nom de chemin dans le système de fichiers pour le document.Provide a path name in the file system for the document. Certaines interfaces utilisateur de débogage utilisent cela afin d’autoriser l’utilisateur à modifier et à enregistrer les modifications apportées au document.Some debugging UIs use this to permit the user to edit and save changes to the document. IDebugDocumentHost::NotifyChanged est appelée pour avertir l’hôte une fois que le document a été enregistré.IDebugDocumentHost::NotifyChanged is called to notify the host after the document has been saved.

Voir aussiSee Also

Présentation du débogage de script actifActive Script Debugging Overview