Declare Statement

Deklariert einen Verweis auf eine in einer externen Datei implementierte Prozedur.

Syntax

[ <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 ]

Bestandteile

Begriff Definition
attributelist Dies ist optional. Siehe Attributliste.
accessmodifier Optional. Dabei kann es sich um eine der folgenden Methoden handeln:

- Öffentlich
- Geschützt
- Freund
- Privat
- Geschützter Freund
- Privat geschützt

Siehe Access levels in Visual Basic.
Shadows Optional. Siehe Schatten.
charsetmodifier Optional. Gibt Zeichensatz- und Dateisucheinformationen an. Dabei kann es sich um eine der folgenden Methoden handeln:

- Ansi (Standard)
- Unicode
- Auto
Sub Optional, aber entweder Sub oder Function muss angezeigt werden. Gibt an, dass die externe Prozedur keinen Wert zurückgibt.
Function Optional, aber entweder Sub oder Function muss angezeigt werden. Gibt an, dass die externe Prozedur einen Wert zurückgibt.
name Erforderlich. Name dieses externen Verweises. Weitere Informationen finden Sie unter "Deklarierte Elementnamen".
Lib Erforderlich. Führt eine Klausel ein Lib , die die externe Datei (DLL oder Coderessource) identifiziert, die eine externe Prozedur enthält.
libname Erforderlich. Name der Datei, die die deklarierte Prozedur enthält.
Alias Optional. Gibt an, dass die deklarierte Prozedur nicht innerhalb ihrer Datei durch den namen identifiziert werden kann, der in name. Sie geben ihre Identifikation in aliasname.
aliasname Erforderlich, wenn Sie das Alias Schlüsselwort verwenden. Zeichenfolge, die die Prozedur auf eine von zwei Arten identifiziert:

Der Eintragspunktname der Prozedur innerhalb der Datei in Anführungszeichen ("")

Oder

Ein Zahlenzeichen (#) gefolgt von einer ganzzahligen Angabe der Ordnungszahl des Einstiegspunkts der Prozedur in der Datei
parameterlist Erforderlich, wenn die Prozedur Parameter verwendet. Siehe Parameterliste.
returntype Erforderlich, wenn Function angegeben und Option Strict ist On. Datentyp des von der Prozedur zurückgegebenen Werts.

Hinweise

Manchmal müssen Sie eine in einer Datei definierte Prozedur (z. B. eine DLL oder Coderessource) außerhalb Ihres Projekts aufrufen. Wenn Sie dies tun, verfügt der Visual Basic Compiler nicht über Zugriff auf die Informationen, die er benötigt, um die Prozedur ordnungsgemäß aufzurufen, z. B. wo sich die Prozedur befindet, wie sie identifiziert wird, ihre Aufrufsequenz und den Rückgabetyp und den Zeichenfolgenzeichensatz, den sie verwendet. Die Declare Anweisung erstellt einen Verweis auf eine externe Prozedur und stellt diese erforderlichen Informationen bereit.

Sie können Declare nur auf Modulebene verwenden. Dies bedeutet, dass der Deklarationskontext für einen externen Verweis eine Klasse, Struktur oder ein Modul sein muss und keine Quelldatei, ein Namespace, eine Schnittstelle, eine Prozedur oder ein Block sein kann. Weitere Informationen finden Sie unter Deklarationskontexte und Standardzugriffsebenen.

Externe Verweise sind standardmäßig auf den öffentlichen Zugriff festgelegt. Sie können ihre Zugriffsebenen mit den Zugriffsmodifizierern anpassen.

Regeln

  • Attribute Sie können Attribute auf einen externen Verweis anwenden. Jedes von Ihnen angewendete Attribut hat nur auswirkungen auf Ihr Projekt, nicht in der externen Datei.

  • Modifizierer. Externe Prozeduren werden implizit freigegeben. Sie können das Shared Schlüsselwort nicht verwenden, wenn Sie einen externen Verweis deklarieren, und Sie können den freigegebenen Status nicht ändern.

    Eine externe Prozedur kann nicht an der Außerkraftsetzung teilnehmen, Schnittstellenelemente implementieren oder Ereignisse behandeln. Dementsprechend können Sie das OverridesMustOverrideNotOverridableImplementsOverridableHandles Schlüsselwort nicht in einer Declare Anweisung verwenden.

  • Name der externen Prozedur. Sie müssen diesen externen Verweis nicht denselben Namen (in ) wie der Einstiegspunktname der Prozedur innerhalb der externen Datei (aliasname) namegeben. Sie können eine Alias Klausel verwenden, um den Eintragspunktnamen anzugeben. Dies kann nützlich sein, wenn die externe Prozedur denselben Namen wie ein Visual Basic reservierter Modifizierer oder eine Variable, Prozedur oder ein anderes Programmierelement im gleichen Bereich hat.

    Hinweis

    Einstiegspunktnamen in den meisten DLLs sind groß- und kleinschreibungsempfindlich.

  • Externe Prozedurnummer. Alternativ können Sie eine Alias Klausel verwenden, um die Ordnungsnummer des Einstiegspunkts in der Exporttabelle der externen Datei anzugeben. Dazu beginnen aliasname Sie mit einem Nummernzeichen (#). Dies kann nützlich sein, wenn ein beliebiges Zeichen im Namen der externen Prozedur in Visual Basic nicht zulässig ist oder wenn die externe Datei die Prozedur ohne Namen exportiert.

Datentypregeln

  • Parameterdatentypen. Wenn Option Strict dies der Wert ist On, müssen Sie den Datentyp der einzelnen Parameter in parameterlist. Dies kann ein beliebiger Datentyp oder der Name einer Enumeration, Struktur, Klasse oder Schnittstelle sein. In parameterlistdiesem Bereich verwenden Sie eine As Klausel, um den Datentyp des Arguments anzugeben, das an jeden Parameter übergeben werden soll.

    Hinweis

    Wenn die externe Prozedur für die .NET Framework nicht geschrieben wurde, müssen Sie darauf achten, dass die Datentypen entsprechen. Wenn Sie z. B. einen externen Verweis auf eine Visual Basic 6.0-Prozedur mit einem Integer Parameter (16 Bit in Visual Basic 6.0) deklarieren, müssen Sie das entsprechende Argument wie Short in der Declare Anweisung identifizieren, da dies der 16-Bit-Ganzzahltyp in Visual Basic ist. Long Ebenso weist eine andere Datenbreite in Visual Basic 6.0 auf und Date wird anders implementiert.

  • Datentyp zurückgeben. Wenn die externe Prozedur ein Function und Option Strict ist On, müssen Sie den Datentyp des werts angeben, der an den aufrufenden Code zurückgegeben wird. Dies kann ein beliebiger Datentyp oder der Name einer Enumeration, Struktur, Klasse oder Schnittstelle sein.

    Hinweis

    Der Visual Basic Compiler überprüft nicht, ob Ihre Datentypen mit denen der externen Prozedur kompatibel sind. Wenn eine Übereinstimmung besteht, generiert die allgemeine Sprachlaufzeit zur Laufzeit eine MarshalDirectiveException Ausnahme.

  • Standarddatentypen. Wenn Option Strict sie den Datentyp eines Parameters nicht parameterlistangeben, konvertiert der Visual Basic Compiler das entsprechende Argument in den ObjektdatentypOff. Wenn Sie nicht angeben returntype, nimmt der Compiler den Rückgabedatentyp auf Object.

    Hinweis

    Da Sie sich mit einem externen Verfahren befassen, das möglicherweise auf einer anderen Plattform geschrieben wurde, ist es gefährlich, alle Annahmen über Datentypen zu treffen oder ihnen die Standardeinstellung zu ermöglichen. Es ist viel sicherer, den Datentyp jedes Parameters und des Rückgabewerts anzugeben, falls vorhanden. Dadurch wird auch die Lesbarkeit des Codes verbessert.

Verhalten

  • Umfang. Ein externer Verweis befindet sich in der gesamten Klasse, Struktur oder des Moduls im Bereich.

  • Lifetime (Lebensdauer). Ein externer Verweis hat dieselbe Lebensdauer wie die Klasse, Struktur oder das Modul, in dem er deklariert wird.

  • Aufrufen einer externen Prozedur. Sie rufen eine externe Prozedur auf die gleiche Weise auf, wie Sie eine FunctionSub Prozedur aufrufen – indem Sie sie in einem Ausdruck verwenden, wenn er einen Wert zurückgibt, oder indem Sie sie in einer Call-Anweisung angeben, wenn sie keinen Wert zurückgibt.

    Sie übergeben Argumente genau wie in der Anweisung angegeben parameterlist an die Declare externe Prozedur. Berücksichtigen Sie nicht, wie die Parameter ursprünglich in der externen Datei deklariert wurden. Wenn ein Rückgabewert vorhanden ist, verwenden Sie ihn ebenso wie in der Declare Anweisung angegebenreturntype.

  • Zeichensätze. Sie können angebencharsetmodifier, wie Visual Basic Zeichenfolgen beim Aufrufen der externen Prozedur marshallal werden sollen. Der Ansi Modifizierer leitet Visual Basic an ANSI-Werte alle Zeichenfolgen zu marshalieren, und der Unicode Modifizierer leitet ihn an alle Zeichenfolgen an Unicode-Werte weiter. Der Auto Modifizierer leitet Visual Basic nach .NET Framework Regeln basierend auf der externen Referenz nameoder aliasname sofern angegeben, an Marshalzeichenfolgen. Der Standardwert ist Ansi.

    charsetmodifiergibt auch an, wie Visual Basic die externe Prozedur innerhalb der externen Datei nachschlagen soll. Ansiund Unicode sowohl direkt Visual Basic, um es nachzuschlagen, ohne den Namen während der Suche zu ändern. Autoleitet Visual Basic, um den Basiszeichensatz der Laufzeitplattform zu bestimmen und möglicherweise den Namen der externen Prozedur wie folgt zu ändern:

    • Auf einer Unicode-Plattform, z. B. Windows, suchen Sie zuerst die externe Prozedur ohne Namensänderung nach. Wenn dies fehlschlägt, fügen Sie "W" am Ende des externen Prozedurnamens an, und suchen Sie es erneut.

    • Auf einer ANSI-Plattform suchen Sie zuerst das externe Verfahren ohne Namensänderung nach. Wenn dies fehlschlägt, fügen Sie "A" am Ende des externen Prozedurnamens an, und suchen Sie es erneut.

  • Mechanismus. Visual Basic verwendet den .NET Framework-Plattform-Aufrufmechanismus (PInvoke), um externe Prozeduren aufzulösen und darauf zuzugreifen. Die Declare Anweisung und die DllImportAttribute Klasse verwenden diesen Mechanismus automatisch, und Sie benötigen keine Kenntnisse von PInvoke. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Aufrufen Windows APIs.

Wichtig

Wenn die externe Prozedur außerhalb der Common Language Runtime (CLR) ausgeführt wird, handelt es sich um nicht verwalteten Code. Wenn Sie eine solche Prozedur aufrufen, z. B. eine Windows API-Funktion oder eine COM-Methode, können Sie Ihre Anwendung Sicherheitsrisiken offenlegen. Weitere Informationen finden Sie unter Secure Coding Guidelines for Unmanaged Code.

Beispiel 1

Im folgenden Beispiel wird ein externer Verweis auf eine Function Prozedur deklariert, die den aktuellen Benutzernamen zurückgibt. Anschließend wird die externe Prozedur als Teil der getUser Prozedur GetUserNameA aufgerufen.

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

Beispiel 2

Dies DllImportAttribute bietet eine alternative Möglichkeit zur Verwendung von Funktionen in nicht verwaltetem Code. Im folgenden Beispiel wird eine importierte Funktion deklariert, ohne eine Declare Anweisung zu verwenden.

' 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

Weitere Informationen