Declare, instruction

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 ]

Pièces

Remarques

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 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. 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ées. Vous ne pouvez pas utiliser le mot clé lors de la Shared 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é , , , ou MustOverrideNotOverridableImplementsle Overrides, Overridabledans Handles une Declare instruction.

• Nom de la procédure externe. Vous n’avez pas besoin de donner à cette référence externe le même nom (in name) que le nom du point d’entrée de la procédure dans son fichier externe (aliasname). Vous pouvez utiliser une Alias clause 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.

  Remarque

  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 Alias clause 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é en 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 c’est Onle cas, 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 As clause pour spécifier le type de données de l’argument à passer à chaque paramètre.

  Remarque

  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 Integer paramètre (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 elle a une largeur de données différente dans Visual Basic 6.0 et Date est implémentée différemment.

• Retourne le type de données. Si la procédure externe est une Function procédure externe, Option StrictOnvous 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.

  Remarque

  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 MarshalDirectiveException exception au moment de l’exécution.

• Types de données par défaut. Si Option Strict c’est Off le cas et si vous ne spécifiez pas le type de données d’un paramètre, parameterlistle compilateur Visual Basic convertit l’argument correspondant en type de données objet. De même, si vous ne spécifiez returntypepas, le compilateur accepte le type de données de retour comme Objectétant .

  Remarque

  É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 une 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 Call si elle ne retourne pas de valeur.

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

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

  charsetmodifier spécifie également comment Visual Basic doit rechercher la procédure externe dans son fichier externe. Ansi et Unicode direct 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 plateforme .NET Framework (PInvoke) pour résoudre et accéder aux procédures externes. L’instruction Declare et la DllImportAttribute classe 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.

Exemple 1

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

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

Il 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

• LastDllError
• Importe l’instruction (Espace de noms et type .NET)
• AddressOf (opérateur)
• Instruction de fonction
• Sous-énoncé
• Liste de paramètres
• Call (instruction)
• Procédure pas à pas : appel d’API Windows