Declare Statement

  • Artikel

Deklariert einen Verweis auf eine Prozedur, die in einer externen Datei implementiert ist.

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:

- Public
- Protected
- Friend
- Privat
- Protected Friend
- Private Protected

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

- Ansi (Standard)
- Unicode
- Auto
Sub Optional, aber es muss Sub oder Function angezeigt werden. Gibt an, dass die externe Prozedur keinen Wert zurückgibt.
Function Optional, aber es muss Sub oder Function angezeigt werden. Gibt an, dass die externe Prozedur einen Wert zurückgibt.
name Erforderlich. Name dieses externen Verweises. Weitere Informationen finden Sie unter Namen deklarierter Elemente.
Lib Erforderlich. Führt eine Lib-Klausel ein, die die externe Datei (DLL- oder Coderessource) mit einer externen Prozedur angibt.
libname Erforderlich. Der Name der Datei, die die deklarierte Prozedur enthält.
Alias Optional. Gibt an, dass die deklarierte Prozedur nicht innerhalb der Datei anhand des in name angegebenen Namens identifiziert werden kann. Sie geben die entsprechende Identifikation in aliasname an.
aliasname Erforderlich, wenn Sie das Alias-Schlüsselwort verwenden. Zeichenfolge, die die Prozedur auf eine von zwei Arten identifiziert:

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

Oder

Ein Nummernzeichen (#) gefolgt von einer ganzen Zahl, die die Ordnungszahl des Einstiegspunkts der Prozedur in der Datei angibt
parameterlist Erforderlich, wenn die Prozedur Parameter verwendet. Siehe Parameterliste.
returntype Erforderlich, wenn Function angegeben wird und Option Strict auf On festgelegt ist. Datentyp des von der Prozedur zurückgegebenen Werts.

Hinweise

Manchmal muss eine Prozedur aufgerufen werden, die in einer Datei (z. B. in einer DLL- oder Coderessource) außerhalb eines bestimmten Projekts definiert ist. In diesem Fall hat der Visual Basic-Compiler keinen 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 Aufruffolge und den Rückgabetyp sowie den von ihm verwendeten Zeichenfolgenzeichensatz. Die Declare-Anweisung erstellt einen Verweis auf eine externe Prozedur und stellt diese erforderlichen Informationen bereit.

Sie können Declare nur auf Modulebene verwenden. Der Deklarationskontext für einen externen Verweis muss demnach eine Klasse, eine Struktur oder ein Modul sein und kann weder eine Quelldatei, noch ein Namespace, eine Prozedur oder ein Block sein. Weitere Informationen finden Sie unter Deklarationskontexte und Standardzugriffsebenen.

Externe Verweise werden standardmäßig auf die Zugriffsstufe Public festgelegt. Sie können ihre Zugriffsebenen mit den Zugriffsmodifizierern anpassen.

Regeln

  • Attribute Attribute können auf einen externen Verweis angewendet werden. Ein angewendetes Attribut hat nur Auswirkungen auf das jeweilige Projekt, nicht in der externen Datei.

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

    Eine externe Prozedur kann nicht an Überschreibungen teilnehmen, Schnittstellenmember implementieren oder Ereignisse behandeln. Dementsprechend können die Schlüsselwörter Overrides, Overridable, NotOverridable, MustOverride, Implementsoder Handles nicht in einer Declare-Anweisung verwendet werden.

  • Name der externen Prozedur. Sie müssen diesem externen Verweis nicht denselben Namen (in name) geben wie dem Einstiegspunktnamen der Prozedur in der externen Datei (aliasname). Sie können eine Alias-Klausel verwenden, um den Einstiegspunktnamen anzugeben. Dies kann hilfreich sein, wenn die externe Prozedur denselben Namen wie ein reservierter Visual Basic-Modifizierer oder eine Variable, Prozedur oder ein anderes Programmierelement im selben Bereich aufweist.

    Hinweis

    Bei Einstiegspunktnamen in den meisten DLLs wird die Groß-/Kleinschreibung beachtet.

  • Nummer der externen Prozedur. Alternativ können Sie eine Alias-Klausel verwenden, um die Ordnungszahl des Einstiegspunkts in der Exporttabelle der externen Datei anzugeben. Dazu beginnen Sie aliasname mit einem Nummernzeichen (#). Dies kann hilfreich sein, wenn ein 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 auf On festgelegt ist, müssen Sie den Datentyp der einzelnen Parameter in parameterlist angeben. Hierbei kann es sich um einen beliebigen Datentyp oder den Namen einer Enumeration, Struktur, Klasse oder Schnittstelle handeln. Innerhalb von parameterlistwird eine As-Klausel verwendet, um den Datentyp des Arguments anzugeben, das an die einzelnen Parameter übergeben werden soll.

    Hinweis

    Wenn die externe Prozedur nicht für .NET Framework geschrieben wurde, müssen Sie darauf achten, dass die Datentypen übereinstimmen. Wenn Sie beispielsweise 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 in der Declare-Anweisung als Short angeben, da dies der ganzzahlige 16-Bit-Typ in Visual Basic ist. Entsprechend hat Long in Visual Basic 6.0 eine andere Datenbreite und Date ist anders implementiert.

  • Rückgabedatentyp. Wenn es sich bei der externen Prozedur um eine Function handelt und Option Strict auf On festgelegt ist, müssen Sie den Datentyp des an den aufrufenden Code zurückgegebenen Werts angeben. Hierbei kann es sich um einen beliebigen Datentyp oder den Namen einer Enumeration, Struktur, Klasse oder Schnittstelle handeln.

    Hinweis

    Der Visual Basic-Compiler überprüft nicht, ob die Datentypen mit denen der externen Prozedur kompatibel sind. Wenn keine Übereinstimmung vorliegt, generiert die Common Language Runtime zur Laufzeit eine MarshalDirectiveException-Ausnahme.

  • Standarddatentypen. Wenn Option Strict auf Off festgelegt ist und Sie den Datentyp eines Parameters in parameterlist nicht angeben, konvertiert der Visual Basic-Compiler das entsprechende Argument in den Object-Datentyp. Wenn Sie returntype nicht angeben, geht der Compiler entsprechend davon aus, dass der Rückgabedatentyp Object lautet.

    Hinweis

    Da eine externe Prozedur vorliegt, die möglicherweise auf einer anderen Plattform geschrieben wurde, ist es gefährlich, Annahmen über Datentypen anzustellen oder sie als Standard zuzulassen. Es ist viel sicherer, ggf. den Datentyp der jeweiligen Parameter und des Rückgabewerts anzugeben. Dadurch verbessert sich auch die Lesbarkeit des Codes.

Verhalten

  • Umfang. Ein externer Verweis befindet sich innerhalb seiner Klasse, Struktur oder des Moduls im Umfang.

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

  • Aufrufen einer externen Prozedur. Eine externe Prozedur wird auf die gleiche Weise aufgerufen wie eine Function- oder Sub-Prozedur, nämlich indem sie in einem Ausdruck verwendet wird, wenn sie einen Wert zurückgibt, oder indem sie in einer Call-Anweisung angegeben wird, wenn sie keinen Wert zurückgibt.

    Argumente werden wie durch parameterlist in der Declare-Anweisung angegeben an die externe Prozedur übergeben. Dabei wird nicht berücksichtigt, wie die Parameter ursprünglich in der externen Datei deklariert wurden. Wenn ein Rückgabewert vorhanden ist, wird er wie durch returntype in der Declare-Anweisung angegeben verwendet.

  • Zeichensätze. In charsetmodifier können Sie angeben, wie Visual Basic beim Aufrufen der externen Prozedur Zeichenfolgen marshallen soll. Der Ansi-Modifizierer weist Visual Basic an, alle Zeichenfolgen an ANSI-Werte zu marshallen, und der Unicode-Modifizierer weist VB an, alle Zeichenfolgen an Unicode-Werte zu marshallen. Der Auto-Modifizierer weist Visual Basic an, Zeichenfolgen ggf. gemäß .NET Framework-Regeln basierend auf dem externen Verweis name oder aliasname zu marshallen. Der Standardwert ist Ansi.

    charsetmodifier gibt auch an, wie Visual Basic die externe Prozedur innerhalb der externen Datei nachschlagen soll. Sowohl Ansi als auch Unicode weisen Visual Basic an, nachzuschlagen, ohne den Namen während der Suche zu ändern. Auto weist Visual Basic an, den Basiszeichensatz der Laufzeitplattform zu bestimmen und möglicherweise den Namen der externen Prozedur wie folgt zu ändern:

    • Schlagen Sie auf einer Unicode-Plattform wie Windows wird zuerst die externe Prozedur ohne Namensänderung nach. Wenn dies nicht gelingt, fügen Sie am Ende des Namens der externen Prozedur „W“ an, und schlagen erneut nach.

    • Schlagen Sie auf einer ANSI-Plattform zuerst die externe Prozedur ohne Namensänderung nach. Wenn dies nicht gelingt, fügen Sie am Ende des Namens der externen Prozedur „A“ an, und schlagen erneut nach.

  • Mechanismus. In Visual Basic wird der .NET Framework-Mechanismus Plattformaufruf (PInvoke) verwendet, um externe Prozeduren aufzulösen und darauf zuzugreifen. Die Declare-Anweisung und die DllImportAttribute-Klasse verwenden diesen Mechanismus automatisch, und Sie müssen sich nicht mit PInvoke auskennen. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Aufrufen von 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 (z. B. eine Windows-API-Funktion oder eine COM-Methode) aufrufen, setzen Sie Ihre Anwendung möglicherweise einem Sicherheitsrisiko aus. Weitere Informationen finden Sie unter Richtlinien für das Schreiben von sicherem, nicht verwaltetem 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 GetUserNameA im Rahmen der getUser-Prozedur 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

Die Klasse DllImportAttribute stellt eine alternative Möglichkeit zum Verwenden von Funktionen in nicht verwaltetem Code dar. 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