Declare

Syntaxe

Paramètres

Description

Ce mot réservé permet de déclarer une référence à une procédure implémentée dans un fichier externe.

Remarques

• Parfois, vous devez appeler une procédure définie dans un fichier (comme une DLL ou une ressource de code) en dehors de votre projet. Lorsque vous effectuez cette opération, le compilateur Visual Basic .NET n'a pas accès aux informations dont il a besoin pour appeler correctement la procédure, telles que l'emplacement de la procédure, la manière dont elle est identifiée, sa séquence d'appel et son type de retour, ainsi que l'ensemble de caractères des usages de chaîne de caractères. L'instruction Declare crée une référence à une procédure externe et fournit les informations nécessaires.
• Vous ne pouvez utiliser Declare qu'au niveau du module. Cela signifie que le contexte de déclaration d'une référence externe doit être une classe, une structure ou un module et ne peut pas être un fichier source, un espace de noms, une interface, une procédure ou un bloc.
• Les références externes par défaut à l'accès public. Vous pouvez ajuster leurs niveaux d'accès avec les modificateurs d'accès.
• Les attributs : Vous pouvez appliquer des attributs à une référence externe. Tout attribut que vous appliquez n'a d'effet que dans votre projet, pas dans le fichier externe.
• Modificateurs : Les procédures externes sont implicitement partagées. Vous ne pouvez pas utiliser le mot clef Shared lors de la déclaration d'une référence externe et vous ne pouvez pas modifier son état partagé.
• Une procédure externe ne peut pas participer au remplacement, implémenter des membres d'interface ou gérer des événements. Par conséquent, vous ne pouvez pas utiliser le mot clef Overrides, Overridable, NotOverridable, MustOverride, Implements ou Handles dans une instruction Declare.
• Nom de la procédure externe : Vous n'êtes pas obligé de donner à cette référence externe le même nom (en nom) que le nom du point d'entrée de la procédure dans son fichier externe (nom d'alias). Vous pouvez utiliser une clause Alias pour spécifier le nom du point d'entrée. Cela peut être utile si la procédure externe porte le même nom qu'un modificateur réservé Visual Basic .NET ou une variable, une procédure ou tout autre élément de programmation dans la même portée. Les noms de point d'entrée dans la plupart des DLL sont sensibles à la casse.
• Numéro de procédure externe : Vous pouvez également utiliser une clause Alias pour spécifier le numéro ordinal du point d'entrée dans la table d'exportation du fichier externe. Pour ce faire, vous commencez le nom d'alias par un signe dièse (#). Cela peut être utile si un caractère du nom de la procédure externe n'est pas autorisé dans Visual Basic .NET ou si le fichier externe exporte la procédure sans nom.
• Types de données de paramètre : Si Option Strict est activé, vous devez spécifier le type de données de chaque paramètre dans la liste de paramètres. Il peut s'agir de n'importe quel type de données ou du nom d'une énumération, d'une structure, d'une classe ou d'une interface. Dans la liste de paramètres, vous utilisez une clause As pour spécifier le type de données dans le paramètre à transmettre à chaque paramètre. Si la procédure externe n'a pas été écrite pour le cadre d'application .NET, vous devez veiller à ce que les types de données correspondent. Par exemple, si vous déclarez une référence externe à une procédure Visual Basic 6.0 avec un paramètre Integer (16 bits dans Visual Basic 6.0), vous devez identifier le paramètre correspondant comme Short dans l'instruction Declare, car il s'agit du type entier 16 bits en Visual Basic. De même, Long a une largeur de données différente dans Visual Basic 6.0 et Date est implémenté différemment.
• Renvoie le type de données : Si la procédure externe est une Function et que Option Strict est On, vous devez spécifier le type de données de la valeur renvoyée au code appelant. Il peut s'agir de n'importe quel type de données ou du nom d'une énumération, d'une structure, d'une classe ou d'une interface. Le compilateur Visual Basic .NET ne vérifie pas que vos types de données sont compatibles avec ceux de la procédure externe. En cas de non-concordance, le Common Language Runtime génère une exception MarshalDirectiveException au moment de l'exécution.
• Types de données par défaut : Si Option Strict est désactivé et que vous ne spécifiez pas le type de données d'un paramètre dans la liste de paramètres, le compilateur Visual Basic .NET convertit le paramètre correspondant en type de données d'objet. De même, si vous ne spécifiez pas returntype, le compilateur considère que le type de données de retour est Object.Parce que vous avez affaire à une procédure externe pouvant avoir été écrite sur une plate-forme différente, il est dangereux de faire des suppositions sur les types de données ou de leur permettre de faire défaut. Il est beaucoup plus sûr de spécifier le type de données de chaque paramètre et de la valeur de retour, le cas échéant. Cela améliore également la lisibilité de votre code.
• Portée : Une référence externe est dans la portée dans toute sa classe, sa structure ou son module.
• Durée de vie : Une référence externe a la même durée de vie que la classe, la structure ou le module dans lequel elle est déclarée.
• Appel d'une procédure externe : Vous appelez une procédure externe de la même manière que vous appelez une procédure Function ou Sub : en l'utilisant dans une expression si elle renvoie une valeur, ou en la spécifiant dans une instruction Call si elle ne renvoie pas de valeur.
• Vous transmettez des paramètres à la procédure externe exactement comme spécifié par la liste de paramètres dans l'instruction Declare. Ne tenez pas compte de la façon dont les paramètres ont été déclarés à l'origine dans le fichier externe. De même, s'il existe une valeur de retour, utilisez-la exactement comme spécifié par returntype dans l'instruction Declare.
• Ensemble de caractères : Vous pouvez spécifier dans charsetmodifier comment Visual Basic .NET doit marshaler les chaînes de caractères lorsqu'il appelle la procédure externe. Le modificateur Ansi ordonne à Visual Basic .NET de marshaler toutes les chaînes de caractères en valeurs ANSI et le modificateur Unicode lui ordonne de marshaler toutes les chaînes de caractères en valeurs Unicode. Le modificateur Auto dirige Visual Basic .NET vers les chaînes de caractères de marshal conformément aux règles le cadre d'application .NET basées sur le nom de référence externe ou le nom d'alias si spécifié. La valeur par défaut est Ansi.
• charsetmodifier spécifie également comment Visual Basic .NET doit rechercher la procédure externe dans son fichier externe. Ansi et Unicode demandent tous deux à Visual Basic .NET de le rechercher sans modifier son nom pendant la recherche. Auto demande à Visual Basic .NET de déterminer l'ensemble de caractères de base de la plate-forme d'exécution et éventuellement de modifier le nom de la procédure externe, comme suit : Sur une plate-forme Unicode, telle que Windows, recherchez d'abord la procédure externe sans modification de nom. Si cela échoue, ajoutez "W" à la fin du nom de la procédure externe et recherchez-le à nouveau. Sur une plate-forme ANSI, recherchez d'abord la procédure externe sans modification de nom. Si cela échoue, ajoutez "A" à la fin du nom de la procédure externe et recherchez-le à nouveau.
• Mécanisme : Le Visual Basic .NET utilise le mécanisme d'appel de plate-forme de cadre d'application .NET (PInvoke) pour résoudre et accéder aux procédures externes. L'instruction Declare et la classe DllImportAttribute utilisent toutes deux ce mécanisme automatiquement et vous n'avez besoin d'aucune connaissance de PInvoke.
• Si la procédure externe s'exécute en dehors du CLR (Common Language Runtime), il s'agit de code non géré. Lorsque vous appelez une telle procédure, par exemple une fonction API Windows ou une méthode COM, vous pouvez exposer votre application à des risques de sécurité.