SAMPLE : XLCLIENT : Client Automation pour Excel

XLCLIENT montre comment contrôler Microsoft Excel à l'aide de OLE Automation. Le répertoire MFC contient un exemple qui utilise MFC. Le répertoire du Kit de développement SDK contient un exemple qui n'utilise pas MFC.

Le fichier suivant est disponible pour téléchargement à partir du Centre de téléchargement Microsoft :
Pour plus d'informations sur la façon de télécharger des fichiers du support technique Microsoft, cliquez sur le numéro ci-dessous pour afficher l'article correspondant dans la base de connaissances Microsoft : Microsoft a analysé ce fichier en vue de détecter la présence de virus. Microsoft a utilisé les logiciels de détection de virus les plus récents qui était disponible sur la date à laquelle le fichier a été validé. Le fichier est stocké sur des serveurs sécurisés, empêchant toute modification non autorisée du fichier. Excel expose ses objets, propriétés et méthodes afin qu'un client puisse y accéder par l'intermédiaire de OLE Automation. Cet exemple montre comment écrire un client automation qui équivaut au code Visual Basic 4.0 suivant qui insère des valeurs dans les cellules et crée un graphique de ces valeurs.

Procédures pour écrire un Client Automation pour Microsoft Excel

Un client automation utilise l'interface IDispatch pour contrôler Microsoft Excel. Les informations suivantes sont applique lors de l'écriture d'un client automation pour Microsoft Excel :

• Lisez la documentation de Microsoft Excel automation méthodes/propriétés qui vous avez l'intention d'utiliser dans le fichier Vba_xl.hlp qui est livré avec Excel.
• Les valeurs des constantes Microsoft Excel comme xlWorkSheet, xl3DPie, xlRows etc. peut être obtenu à partir de l'article suivant de la base de connaissances Microsoft :
  112671  (http://support.microsoft.com/kb/112671/EN-US/ ) Désactivée (OFF): «intégrés constantes dans Visual Basic pour applications"(WC0993)
  Ces valeurs de constante peuvent également être obtenues à partir de la bibliothèque de type de Microsoft Excel à l'aide d'un navigateur de bibliothèque de type comme Ole2vw32.exe (dans le répertoire \bin de la fonction du compilateur). Ouvrez la bibliothèque de type de Microsoft Excel (for example, Xl5en32.olb pour la version américaine de Microsoft Excel 95) à l'aide du menu fichier/ViewTypeLibrary de Ole2vw32.exe. Supprimer la zone de liste déroulante typeinfos et sélectionnez «constantes». Les constantes Microsoft Excel seront affichés dans la zone de liste de variables/DataMembers.
• Tous les arguments et des types de retour des méthodes d'automatisation de Microsoft Excel et les types sont de type VARIANT. Les types réels qui doivent être définis dans et récupéré à partir d'un objet de type VARIANT ne sont pas explicitement indiqués dans Vba_xl.hlp. Cependant les types peuvent être devinés facilement à partir de la documentation. Par exemple, un nombre peut être passé en tant que VT_I2, une chaîne comme VT_BSTR et un objet comme VT_DISPATCH. Microsoft Excel ne les contraintes appropriées si nécessaire. Valeurs renvoyées par Microsoft Excel peuvent être devinés de la même façon. Si le type exact de la valeur de retour ne peut pas être déterminé activer la case à cocher VARIANT.vt ou de forcer le type de retour à l'aide de VariantChangeType. Comme indiqué dans «Microsoft Excel spécificités» section du chapitre 7 dans le Kit du développeur Microsoft Excel dans le Kit du développeur Office sur le CD-ROM de MSDN, Microsoft Excel ne retournera jamais un VARIANT dont le type de données qui ne figure pas dans la liste suivante :

     Data Type                               Variant Constant
     ---------                               ----------------
     Boolean                                 VT_BOOL
     Currency (scaled integer)               VT_CY
     Date                                    VT_DATE
     Error cell values (#N/A, #REF etc.)     VT_ERROR
     Integer                                 VT_I2
     Long (long integer)                     VT_I4
     Object                                  VT_DISPATCH
     Single (single-precision floating-point)VT_R4
     Double (double-precision floating-point)VT_R8
     String                                  VT_BSTR
  						

Les informations suivantes sont applique à tous les clients automation :

• OLE utilise des chaînes Unicode. La macro OLESTR peut être utilisée pour convertir des constantes de chaîne pour les chaînes Unicode. Dans MFC, les variables qui contiennent les chaînes peuvent être convertis vers et à partir de Unicode à l'aide de macros T2OLE et OLE2T. Voir MFC TechNote 59 pour plus d'informations. Code qui n'utilise pas MFC peut trouver des informations pour la conversion Unicode/ANSI dans l'article suivant de la base de connaissances :
  
  Procédure à suivre pour effectuer la conversion d'ANSI en Unicode et Unicode en ANSI pour OLE ID :138813  (http://support.microsoft.com/kb/138813/EN-US/ )
• L'appelant d'une méthode OLE API ou l'interface est responsable de la libération des arguments et les valeurs de retour.

Procédures pour écrire un Client Automation MFC pour Microsoft Excel

1. Utiliser AppWizard pour créer une application avec automation prennent en charge.
2. Sélectionnez l'onglet de OLE Automation dans l'Assistant classe et sélectionnez AddClass / à partir d'un TypeLibrary OLE. Sélectionnez bibliothèque de type d'Excel (Xl5en32.olb pour États-Unis version de Microsoft Excel 95) dans le répertoire de Microsoft Excel. Sélectionnez les objets Microsoft Excel que vous utiliserez. ClassWizard créera une classe de proxy dérivée de COleDispatchDriver pour chaque objet que vous sélectionnez. L'exemple sélectionné les objets application, Range, Workbook, classeurs, feuille de calcul, graphique et les graphiques Excel et ClassWizard créé les nouvelles classes dans Xl5en32.h et Xl5en32.h. Modifier le nom de la méthode de l'objet Range objet à un autre nom (par exemple, boîte de dialogue), car les fichiers d'en-tête système définissent DialogBox que DialogBoxA ou DialogBoxW de DialogBox.
3. Inclure le fichier d'en-tête généré à l'étape 2 dans le fichier .cpp qui contient le code pour contrôler Microsoft Excel.
4. Arguments facultatifs qui ne sont pas transmises peuvent être indiqués en passant un objet de type VARIANT contenant VT_ERROR/DISP_E_PARAMNOTFOUND.
5. Certaines méthodes de Microsoft Excel peuvent être appelées à l'aide de deux syntaxes, comme indiqué dans Vba_xl.hlp. Par exemple, la méthode Workbooks est documentée comme suit :
   Syntaxe 1
   Object.Workbooks(index)
   
   Syntaxe 2
   Object.Workbooks
   ClassWizard générera une seule méthode. Par conséquent, si vous avez besoin d'utiliser la syntaxe autre, modifier le .h généré et le fichier .cpp pour ajouter une autre méthode pour les autres éléments de syntaxe. Par exemple cet exemple ajouté Workbooks2 à la classe d'application comme suit pour correspondre à la syntaxe 2 de la méthode WorkBooks :

      VARIANT Application::Workbooks2()
      {
      VARIANT result;
      InvokeHelper(0x23c, DISPATCH_METHOD, VT_VARIANT, (void*)&result, NULL);
      return result;
      }
   						

   Workbooks2 a le même DISPID (0x23c) en tant que classeurs mais n'a pas d'arguments. Ce problème ne peut pas être résolu en passant VT_ERROR/DISP_E_PAMNOTFOUND. Toutes les méthodes marquées comme ayant deux syntaxes doit être gérée de cette manière.
   
   L'exemple utilise les méthodes Range, des classeurs et des graphiques, toutes dotées de deux syntaxes. Par conséquent, il ajoute Range1, Workbooks2 et Charts2.
6. Classe de COleDispatchDriver de MFC ne prend pas en charge les arguments nommés. Les arguments doivent être passés par position.
7. Si Microsoft Excel génère une exception, il retournera DISP_E_EXCEPTION de IDispatch::Invoke et remplira paramètre EXCEPINFO de cette méthode. MFC lèvera une COleDispatchException lorsque cela se produit et le client peut obtenir les informations d'erreur dans la structure EXCEPINFO en interceptant cette exception.
8. Le code de Doc.cpp dans l'exemple montre comment contrôler Microsoft Excel à l'aide des classes MFC.

Comment écrire un client automation non-MFC pour Microsoft Excel

1. Les fonctions d'assistance, CreateObject et Invoke dans Invhelp.cpp et Invhelp.h de l'exemple BROWSE dans le Kit de développement Win32 SDK permet de facilement écrire un client automation non-MFC. Une autre approche consiste à appeler directement IDispatch::Invoke. Appeler utilise liaison tardive pour contrôler un serveur. Il peut être effectuée plus efficace en modifiant à utiliser dans lequel le DISPID est obtenu à partir du type de liaison id-bibliothèque plutôt que par le biais de IDispatch::GetIDsOfNames.
2. La fonction d'assistance Invoke ne prend pas en charge les arguments nommés. Les arguments doivent être passés par position.
3. La fonction d'assistance Invoke permet une structure EXCEPINFO pour être passée en tant qu'un des paramètres. Microsoft Excel remplit cette structure avec des informations d'erreur si elle déclenche une exception et si un EXCEPINFO structure est fournie par le client. Appel va retourner DISP_E_EXCEPTION lorsque Microsoft Excel génère une exception. Les chaînes dans le EXCEPINFO structure doit être libérée par le client. L'exemple de code ne passe pas d'une structure EXCEPINFO vers Microsoft Excel.
4. Le code de Xlclient.cpp dans l'exemple montre comment contrôler Microsoft Excel.