Declare Statement

  • Article

Déclare une référence à une procédure implémentée dans un fichier externe.

Syntaxe

[ <attributelist> ] [ accessmodifier ] [ Shadows ] [ Overloads ] _
Declare [ charsetmodifier ] [ Sub ] name Lib "libname" _
[ Alias "aliasname" ] [ ([ parameterlist ]) ]
' -or-
[ <attributelist> ] [ accessmodifier ] [ Shadows ] [ Overloads ] _
Declare [ charsetmodifier ] [ Function ] name Lib "libname" _
[ Alias "aliasname" ] [ ([ parameterlist ]) ] [ As returntype ]

Éléments

Terme Définition
attributelist Optionnel. Consultez la Liste des attributs.
accessmodifier Optionnel. Il peut s'agir d'une des méthodes suivantes :

- Public
- Protected
- Friend
- Privé
- Ami protégé
- Private Protected

Consultez Access levels in Visual Basic.
Shadows Optionnel. Consultez Shadows.
charsetmodifier Optionnel. Spécifie le jeu de caractères et les informations de recherche de fichier. Il peut s'agir d'une des méthodes suivantes :

- Ansi (par défaut)
- Unicode
- Auto
Sub Facultatif, mais Sub ou Function doit apparaître. Indique que la procédure externe ne retourne pas de valeur.
Function Facultatif, mais Sub ou Function doit apparaître. Indique que la procédure externe retourne une valeur.
name Obligatoire. Nom de cette référence externe. Pour plus d’informations, consultez Noms d’éléments déclarés.
Lib Obligatoire. Introduit une clause Lib, qui identifie le fichier externe (DLL ou ressource de code) qui contient une procédure externe.
libname Obligatoire. Nom du fichier qui contient la procédure déclarée.
Alias Optionnel. Indique que la procédure déclarée ne peut pas être identifiée dans son fichier par le nom spécifié dans name. Vous spécifiez son identification dans aliasname.
aliasname Obligatoire si vous utilisez le mot clé Alias. Chaîne qui identifie la procédure de l’une des deux manières suivantes :

Nom du point d’entrée de la procédure dans son fichier, entre guillemets ("")

-ou-

Signe numérique (#) suivi d’un entier spécifiant le nombre ordinal du point d’entrée de la procédure dans son fichier
parameterlist Obligatoire si la procédure prend des paramètres. Consultez la Liste des paramètres.
returntype Obligatoire si Function est spécifié et Option Strict est On. Le type de données de la valeur retournée par la procédure.

Notes

Parfois, vous devez appeler une procédure définie dans un fichier (par exemple, une DLL ou une ressource de code) en dehors de votre projet. Lorsque vous effectuez cette opération, le compilateur Visual Basic n’a pas accès aux informations dont il a besoin pour appeler la procédure correctement, comme l’emplacement de la procédure, la façon dont elle est identifiée, sa séquence d’appel et son type de retour, et le jeu de caractères de chaîne qu’il utilise. L’instruction Declare crée une référence à une procédure externe et fournit ces informations nécessaires.

Vous pouvez utiliser Declare seulement 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. Pour plus d’informations, consultez Contextes de déclaration et niveaux d’accès par défaut.

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.

Règles

  • Attributs. Vous pouvez appliquer des attributs à une référence externe. Tout attribut que vous appliquez n’a effet que dans votre projet, et non dans le fichier externe.

  • Modificateurs. Les procédures externes sont implicitement Partagés. Vous ne pouvez pas utiliser le mot clé 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 à la substitution, implémenter des membres d’interface ou gérer des événements. En conséquence, vous ne pouvez pas utiliser le mot clé Overrides, Overridable, NotOverridable, MustOverride, Implements ou Handles dans une instruction Declare.

  • Nom de la procédure externe. Vous n’avez pas besoin de donner à cette référence externe le même nom (dans name) que le nom du point d’entrée de la procédure dans son fichier externe (aliasname). 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 ou une variable, une procédure ou tout autre élément de programmation dans la même étendue.

    Notes

    Les noms de points d’entrée dans la plupart des DLL respectent la casse.

  • Numéro de procédure externe. Vous pouvez également utiliser une clause Alias pour spécifier le nombre ordinal du point d’entrée dans la table d’exportation du fichier externe. Pour ce faire, commencez aliasname par un signe numérique (#). Cela peut être utile si un caractère du nom de procédure externe n’est pas autorisé dans Visual Basic ou si le fichier externe exporte la procédure sans nom.

Règles de type de données

  • Types de données de paramètre. Si Option Strict est On, vous devez spécifier le type de données de chaque paramètre dans parameterlist. 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 parameterlist, vous utilisez une clause As pour spécifier le type de données de l’argument à passer à chaque paramètre.

    Notes

    Si la procédure externe n’a pas été écrite pour le .NET Framework, vous devez vous assurer 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 l’argument correspondant comme Short dans l’instruction Declare, car il s’agit du type entier 16 bits dans Visual Basic. De même, Long a une largeur de données différente dans Visual Basic 6.0 et Date est implémentée différemment.

  • Type de données de retour. Si la procédure externe est Function et Option Strict est Onvous devez spécifier le type de données de la valeur retourné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.

    Notes

    Le compilateur Visual Basic ne vérifie pas que vos types de données sont compatibles avec ceux de la procédure externe. S’il existe une incompatibilité, 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 Off et si vous ne spécifiez pas le type de données d’un paramètre dans parameterlist, le compilateur Visual Basic convertit l’argument correspondant en type de données objet. De même, si vous ne spécifiez pas returntype, le compilateur accepte le type de données de retour comme étant Object.

    Notes

    Étant donné que vous traitez d’une procédure externe qui a peut-être été écrite sur une autre plateforme, il est dangereux de faire des hypothèses sur les types de données ou de les autoriser par 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.

Comportement

  • Portée. Une référence externe est dans l’étendue de sa classe, de sa structure ou de 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 façon que vous appelez un Function ou Sub une procédure, en l’utilisant dans une expression si elle retourne une valeur, ou en la spécifiant dans une instruction d’appel si elle ne retourne pas de valeur.

    Vous passez des arguments à la procédure externe exactement comme spécifié par parameterlist dans l’instruction Declare. Ne prenez pas en compte 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.

  • Jeux de caractères. Vous pouvez spécifier dans charsetmodifier la façon dont Visual Basic doit marshaler des chaînes lorsqu’il appelle la procédure externe. Le modificateur Ansi dirige Visual Basic pour marshaler toutes les chaînes vers des valeurs ANSI, et le modificateur Unicode le dirige pour marshaler toutes les chaînes vers des valeurs Unicode. Le modificateur Auto dirige Visual Basic pour marshaler des chaînes en fonction des règles .NET Framework basées sur la référence externe name, ou aliasname si elle est spécifiée. La valeur par défaut est Ansi.

    charsetmodifier spécifie également la façon dont Visual Basic doit rechercher la procédure externe dans son fichier externe. Ansi et Unicode dirigent tous deux Visual Basic pour le rechercher sans modifier son nom pendant la recherche. Auto dirige Visual Basic pour déterminer le jeu de caractères de base de la plateforme d’exécution et éventuellement modifier le nom de la procédure externe, comme suit :

    • Sur une plateforme 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 plateforme 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. Visual Basic utilise le mécanisme d’appel de code non managé .NET Framework (PInvoke) pour résoudre et accéder aux procédures externes. L’instruction Declare et la classe DllImportAttribute utilisent automatiquement ce mécanisme, et vous n’avez pas besoin de connaissances sur PInvoke. Pour plus d’informations, consultez Procédure pas à pas : appel d’API Windows.

Important

Si la procédure externe s’exécute en dehors du Common Language Runtime (CLR), il s’agit d’un code non managé. 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é. Pour plus d’informations, consultez Instructions de codage sécurisé pour le code non managé.

Exemple 1

L’exemple suivant déclare une référence externe à une procédure Function qui retourne le nom d’utilisateur actuel. Il appelle ensuite la procédure externe GetUserNameA dans le cadre de la procédure getUser.

Declare Function GetUserName Lib "advapi32.dll" Alias "GetUserNameA" (
    ByVal lpBuffer As String, ByRef nSize As Integer) As Integer
Sub GetUser()
    Dim buffer As String = New String(CChar(" "), 25)
    Dim retVal As Integer = GetUserName(buffer, 25)
    Dim userName As String = Strings.Left(buffer, InStr(buffer, Chr(0)) - 1)
    MsgBox(userName)
End Sub

Exemple 2

Le DllImportAttribute fournit une autre façon d’utiliser des fonctions dans du code non managé. L’exemple suivant déclare une fonction importée sans utiliser d’instruction Declare.

' Add an Imports statement at the top of the class, structure, or
' module that uses the DllImport attribute.
Imports System.Runtime.InteropServices

<DllImportAttribute("kernel32.dll", EntryPoint:="MoveFileW",
    SetLastError:=True, CharSet:=CharSet.Unicode,
    ExactSpelling:=True,
    CallingConvention:=CallingConvention.StdCall)>
Public Shared Function MoveFile(ByVal src As String,
  ByVal dst As String) As Boolean
    ' This function copies a file from the path src to the path dst.
    ' Leave this function empty. The DLLImport attribute forces calls
    ' to MoveFile to be forwarded to MoveFileW in KERNEL32.DLL.
End Function

Voir aussi