Delen via

Instructie declareren

  • Artikel

Declareert een verwijzing naar een procedure die is geïmplementeerd in een extern bestand.

Syntaxis

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

generator

Term Definitie
attributelist Optioneel. Zie de lijst met kenmerken.
accessmodifier Optioneel. Dit kan een van de volgende zijn:

- Openbaar
- Beschermd
- Vriend
- Privé
- Beveiligde vriend
- Privé beveiligd

Zie Access-niveaus in Visual Basic.
Shadows Optioneel. Zie schaduwen.
charsetmodifier Optioneel. Hiermee geeft u tekenset en bestand zoeken informatie. Dit kan een van de volgende zijn:

- Ansi (standaard)
- Unicode
- Auto
Sub Optioneel, maar Sub wel of Function moet worden weergegeven. Geeft aan dat de externe procedure geen waarde retourneert.
Function Optioneel, maar Sub wel of Function moet worden weergegeven. Geeft aan dat de externe procedure een waarde retourneert.
name Vereist. Naam van deze externe verwijzing. Zie Gedeclareerde elementnamen voor meer informatie.
Lib Vereist. Introduceert een Lib component, die het externe bestand (DLL of coderesource) identificeert dat een externe procedure bevat.
libname Vereist. Naam van het bestand dat de gedeclareerde procedure bevat.
Alias Optioneel. Geeft aan dat de procedure die wordt gedeclareerd, niet kan worden geïdentificeerd in het bestand door de naam die is opgegeven in name. U geeft de identificatie op in aliasname.
aliasname Vereist als u het Alias trefwoord gebruikt. Tekenreeks die de procedure op twee manieren identificeert:

De naam van het toegangspunt van de procedure binnen het bestand, tussen aanhalingstekens ("")

– of –

Een getalteken (#) gevolgd door een geheel getal dat het rangnummer van het toegangspunt van de procedure in het bestand aangeeft
parameterlist Vereist als de procedure parameters gebruikt. Zie de lijst met parameters.
returntype Vereist als Function is opgegeven en Option Strict is On. Gegevenstype van de waarde die door de procedure wordt geretourneerd.

Opmerkingen

Soms moet u een procedure aanroepen die is gedefinieerd in een bestand (zoals een DLL of coderesource) buiten uw project. Wanneer u dit doet, heeft de Visual Basic-compiler geen toegang tot de informatie die nodig is om de procedure correct aan te roepen, zoals waar de procedure zich bevindt, hoe deze wordt geïdentificeerd, de aanroepende reeks en het retourtype en de tekenreekstekenset die wordt gebruikt. De Declare instructie maakt een verwijzing naar een externe procedure en levert deze noodzakelijke informatie.

U kunt alleen op moduleniveau gebruiken Declare . Dit betekent dat de declaratiecontext voor een externe verwijzing een klasse, structuur of module moet zijn en geen bronbestand, naamruimte, interface, procedure of blok mag zijn. Zie Declaratiecontexten en standaardtoegangsniveaus voor meer informatie.

Externe verwijzingen zijn standaard ingesteld op Openbare toegang. U kunt hun toegangsniveaus aanpassen met de toegangsaanpassingen.

Regels

  • Kenmerken. U kunt kenmerken toepassen op een externe verwijzing. Elk kenmerk dat u toepast, heeft alleen effect in uw project, niet in het externe bestand.

  • Modifiers. Externe procedures worden impliciet gedeeld. U kunt het trefwoord niet gebruiken bij het Shared declareren van een externe verwijzing en u kunt de gedeelde status ervan niet wijzigen.

    Een externe procedure kan niet deelnemen aan het overschrijven, implementeren van interfaceleden of het afhandelen van gebeurtenissen. Daarom kunt u de Overridesinstructie , Overridable, , NotOverridable, MustOverride, of ImplementsHandles trefwoord Declare niet gebruiken.

  • Naam van externe procedure. U hoeft deze externe verwijzing niet dezelfde naam (in name) te geven als de naam van het ingangspunt van de procedure in het externe bestand (aliasname). U kunt een Alias component gebruiken om de naam van het toegangspunt op te geven. Dit kan handig zijn als de externe procedure dezelfde naam heeft als een gereserveerde wijzigingsfunctie voor Visual Basic of een variabele, procedure of een ander programmeerelement in hetzelfde bereik.

    Notitie

    Namen van invoerpunten in de meeste DLL's zijn hoofdlettergevoelig.

  • Nummer van externe procedure. U kunt ook een Alias component gebruiken om het rangnummer van het toegangspunt in de exporttabel van het externe bestand op te geven. Hiervoor begint aliasname u met een nummerteken (#). Dit kan handig zijn als een teken in de naam van de externe procedure niet is toegestaan in Visual Basic of als het externe bestand de procedure zonder naam exporteert.

Regels voor gegevenstypen

  • Parametergegevenstypen. Als Option Strict dat het is On, moet u het gegevenstype van elke parameter opgeven in parameterlist. Dit kan elk gegevenstype zijn of de naam van een opsomming, structuur, klasse of interface. Binnen parameterlistgebruikt u een As component om het gegevenstype van het argument op te geven dat aan elke parameter moet worden doorgegeven.

    Notitie

    Als de externe procedure niet is geschreven voor .NET Framework, moet u ervoor zorgen dat de gegevenstypen overeenkomen. Als u bijvoorbeeld een externe verwijzing naar een Visual Basic 6.0-procedure declareert met een Integer parameter (16 bits in Visual Basic 6.0), moet u het bijbehorende argument identificeren zoals Short in de Declare instructie, omdat dat het 16-bits geheel getaltype is in Visual Basic. Heeft ook Long een andere gegevensbreedte in Visual Basic 6.0 en Date wordt anders geïmplementeerd.

  • Gegevenstype retourneren. Als de externe procedure een Function en Option Strict ander is On, moet u het gegevenstype opgeven van de waarde die wordt geretourneerd aan de aanroepende code. Dit kan elk gegevenstype zijn of de naam van een opsomming, structuur, klasse of interface.

    Notitie

    De Visual Basic-compiler controleert niet of uw gegevenstypen compatibel zijn met die van de externe procedure. Als er sprake is van een niet-overeenkomende taalruntime, genereert de algemene taalruntime een MarshalDirectiveException uitzondering.

  • Standaardgegevenstypen. Als Option Strict dat het is Off en u het gegevenstype van een parameter niet opgeeft parameterlist, converteert de Visual Basic-compiler het bijbehorende argument naar het objectgegevenstype. Als u dit niet opgeeftreturntype, neemt de compiler ook het retourgegevenstype.Object

    Notitie

    Omdat u te maken hebt met een externe procedure die mogelijk op een ander platform is geschreven, is het gevaarlijk om veronderstellingen over gegevenstypen uit te voeren of deze standaard toe te staan. Het is veel veiliger om het gegevenstype van elke parameter en van de retourwaarde op te geven, indien van toepassing. Dit verbetert ook de leesbaarheid van uw code.

Gedrag

  • Reikwijdte. Een externe verwijzing valt binnen het bereik van de klasse, structuur of module.

  • Levensduur. Een externe verwijzing heeft dezelfde levensduur als de klasse, structuur of module waarin deze wordt gedeclareerd.

  • Een externe procedure aanroepen. U roept een externe procedure op dezelfde manier aan als u een Function of Sub procedure aanroept, door deze te gebruiken in een expressie als deze een waarde retourneert of door deze op te geven in een aanroepinstructie als deze geen waarde retourneert.

    U geeft argumenten door aan de externe procedure, precies zoals opgegeven parameterlist in de Declare instructie. Houd niet rekening met de manier waarop de parameters oorspronkelijk zijn gedeclareerd in het externe bestand. Als er ook een retourwaarde is, gebruikt u deze precies zoals opgegeven returntype in de Declare instructie.

  • Tekensets. U kunt opgeven charsetmodifier hoe Visual Basic marshal strings moet gebruiken wanneer deze de externe procedure aanroept. De Ansi wijzigingsfunctie stuurt Visual Basic naar marshal alle tekenreeksen naar ANSI-waarden en de Unicode wijzigingsfunctie stuurt deze door naar marshal alle tekenreeksen naar Unicode-waarden. De Auto wijzigingsfunctie stuurt Visual Basic naar marshal strings op basis van .NET Framework-regels op basis van de externe verwijzing name, of aliasname indien opgegeven. De standaardwaarde is Ansi.

    charsetmodifier geeft ook op hoe Visual Basic de externe procedure in het externe bestand moet opzoeken. Ansi en Unicode beide direct Visual Basic om deze op te zoeken zonder de naam ervan te wijzigen tijdens de zoekopdracht. Auto Stuurt Visual Basic om de basistekenset van het runtimeplatform te bepalen en mogelijk de naam van de externe procedure als volgt te wijzigen:

    • Zoek op een Unicode-platform, zoals Windows, eerst de externe procedure op zonder naamwijziging. Als dat mislukt, voegt u 'W' toe aan het einde van de externe procedurenaam en zoekt u deze opnieuw op.

    • Zoek op een ANSI-platform eerst de externe procedure op zonder naamwijziging. Als dat mislukt, voegt u 'A' toe aan het einde van de externe procedurenaam en zoekt u deze opnieuw op.

  • Mechanisme. Visual Basic maakt gebruik van het mechanisme voor aanroepen van het .NET Framework-platform (PInvoke) om externe procedures op te lossen en te openen. De Declare instructie en de DllImportAttribute klasse gebruiken dit mechanisme automatisch en u hebt geen kennis van PInvoke nodig. Zie Walkthrough: Windows-API's aanroepen voor meer informatie.

Belangrijk

Als de externe procedure wordt uitgevoerd buiten de Common Language Runtime (CLR), is dit niet-beheerde code. Wanneer u een dergelijke procedure aanroept, bijvoorbeeld een Windows API-functie of een COM-methode, kunt u uw toepassing blootstellen aan beveiligingsrisico's. Zie Richtlijnen voor veilige codering voor niet-beheerde code voor meer informatie.

Voorbeeld 1

Het volgende voorbeeld declareert een externe verwijzing naar een Function procedure die de huidige gebruikersnaam retourneert. Vervolgens wordt de externe procedure GetUserNameA aanroepen als onderdeel van de getUser procedure.

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

Voorbeeld 2

De DllImportAttribute functie biedt een alternatieve manier om functies in onbeheerde code te gebruiken. In het volgende voorbeeld wordt een geïmporteerde functie gedeclareerde zonder een Declare instructie te gebruiken.

' 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

Zie ook