Deklarera -instruktion

  • Artikel

Deklarerar en referens till en procedur som implementerats i en extern fil.

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 ]

Delar

Period Definition
attributelist Valfritt. Se Attributlista.
accessmodifier Valfritt. Kan vara något av följande:

- Offentliga
- Skyddade
- Vän
- Privat
- Skyddad vän
- Privat skyddad

Se Åtkomstnivåer i Visual Basic.
Shadows Valfritt. Se Skuggor.
charsetmodifier Valfritt. Anger teckenuppsättning och filsökningsinformation. Kan vara något av följande:

- Ansi (standard)
- Unicode
- Auto
Sub Valfritt, men antingen Sub eller Function måste visas. Anger att den externa proceduren inte returnerar något värde.
Function Valfritt, men antingen Sub eller Function måste visas. Anger att den externa proceduren returnerar ett värde.
name Obligatoriska. Namnet på den här externa referensen. Mer information finns i Namn på deklarerade element.
Lib Obligatoriska. Introducerar en Lib sats som identifierar den externa filen (DLL eller kodresurs) som innehåller en extern procedur.
libname Obligatoriska. Namnet på filen som innehåller den deklarerade proceduren.
Alias Valfritt. Anger att proceduren som deklareras inte kan identifieras i filen med det namn som anges i name. Du anger dess identifiering i aliasname.
aliasname Krävs om du använder nyckelordet Alias . Sträng som identifierar proceduren på något av två sätt:

Startpunktens namn på proceduren i filen, inom citattecken ("")

-eller-

Ett taltecken (#) följt av ett heltal som anger ordningstalet för procedurens startpunkt i filen
parameterlist Krävs om proceduren tar parametrar. Se Parameterlista.
returntype Krävs om Function anges och Option Strict är On. Datatyp för det värde som returneras av proceduren.

Kommentarer

Ibland måste du anropa en procedur som definierats i en fil (till exempel en DLL eller kodresurs) utanför projektet. När du gör detta har Visual Basic-kompilatorn inte åtkomst till den information som krävs för att anropa proceduren korrekt, till exempel var proceduren finns, hur den identifieras, dess anropssekvens och returtyp samt strängteckenuppsättningen som används. Instruktionen Declare skapar en referens till en extern procedur och tillhandahåller den nödvändiga informationen.

Du kan bara använda Declare på modulnivå. Det innebär att deklarationskontexten för en extern referens måste vara en klass, struktur eller modul och får inte vara en källfil, namnrymd, gränssnitt, procedur eller blockering. Mer information finns i Deklarationskontexter och standardåtkomstnivåer.

Externa referenser är standard för offentlig åtkomst. Du kan justera deras åtkomstnivåer med åtkomstmodifierarna.

Regler

  • Attribut. Du kan använda attribut för en extern referens. Alla attribut som du tillämpar gäller endast i projektet, inte i den externa filen.

  • Modifierare. Externa procedurer delas implicit. Du kan inte använda nyckelordet Shared när du deklarerar en extern referens och du kan inte ändra dess delade status.

    En extern procedur kan inte delta i att åsidosätta, implementera gränssnittsmedlemmar eller hantera händelser. Därför kan du inte använda nyckelordet Overrides, Overridable, NotOverridable, MustOverride, Implementseller Handles i en Declare -instruktion.

  • Namn på extern procedur. Du behöver inte ge den här externa referensen samma namn (i name) som procedurens startpunktsnamn i den externa filen (aliasname). Du kan använda en Alias sats för att ange startpunktsnamnet. Detta kan vara användbart om den externa proceduren har samma namn som en reserverad modifierare för Visual Basic eller en variabel, procedur eller något annat programmeringselement i samma omfång.

    Kommentar

    Startpunktsnamn i de flesta DLL:er är skiftlägeskänsliga.

  • Externt procedurnummer. Du kan också använda en Alias sats för att ange ordningstalet för startpunkten i exporttabellen för den externa filen. För att göra detta börjar aliasname du med ett taltecken (#). Detta kan vara användbart om något tecken i det externa procedurnamnet inte tillåts i Visual Basic, eller om den externa filen exporterar proceduren utan namn.

Regler för datatyp

  • Parameterdatatyper. Om Option Strict är Onmåste du ange datatypen för varje parameter i parameterlist. Det kan vara valfri datatyp eller namnet på en uppräkning, struktur, klass eller gränssnitt. I parameterlistanvänder du en As -sats för att ange datatypen för argumentet som ska skickas till varje parameter.

    Kommentar

    Om den externa proceduren inte har skrivits för .NET Framework måste du se till att datatyperna motsvarar dem. Om du till exempel deklarerar en extern referens till en Visual Basic 6.0-procedur med en Integer parameter (16 bitar i Visual Basic 6.0) måste du identifiera motsvarande argument som Short i -instruktionen Declare , eftersom det är 16-bitars heltalstypen i Visual Basic. Long På samma sätt har en annan databredd i Visual Basic 6.0 och Date implementeras på olika sätt.

  • Returnera datatyp. Om den externa proceduren är en Function och Option Strict är Onmåste du ange datatypen för det värde som returneras till den anropande koden. Det kan vara valfri datatyp eller namnet på en uppräkning, struktur, klass eller gränssnitt.

    Kommentar

    Visual Basic-kompilatorn verifierar inte att dina datatyper är kompatibla med dem i den externa proceduren. Om det finns ett matchningsfel genererar den vanliga språkkörningen ett MarshalDirectiveException undantag vid körning.

  • Standarddatatyper. Om Option Strict är Off och du inte anger datatypen för en parameter i parameterlistkonverterar Visual Basic-kompilatorn motsvarande argument till objektdatatypen. På samma sätt, om du inte anger returntype, tar kompilatorn returdatatypen till Object.

    Kommentar

    Eftersom du har att göra med en extern procedur som kan ha skrivits på en annan plattform är det farligt att göra några antaganden om datatyper eller att tillåta dem som standard. Det är mycket säkrare att ange datatypen för varje parameter och returvärdet, om det finns. Detta förbättrar också kodens läsbarhet.

Funktionssätt

  • Omfattning. En extern referens finns i omfånget i dess klass, struktur eller modul.

  • Livslängd. En extern referens har samma livslängd som den klass, struktur eller modul där den deklareras.

  • Anropar en extern procedur. Du anropar en extern procedur på samma sätt som du anropar en Function eller Sub -procedur– genom att använda den i ett uttryck om det returnerar ett värde eller genom att ange det i en anropsinstruktur om det inte returnerar ett värde.

    Du skickar argument till den externa proceduren exakt enligt vad som anges i parameterlist -instruktionen Declare . Ta inte hänsyn till hur parametrarna ursprungligen deklarerades i den externa filen. På samma sätt, om det finns ett returvärde, använder du det exakt som anges av returntype i -instruktionen Declare .

  • Teckenuppsättningar. Du kan ange i charsetmodifier hur Visual Basic ska konvertera strängar när den anropar den externa proceduren. Modifieraren Ansi dirigerar Visual Basic till att konvertera alla strängar till ANSI-värden, och Unicode modifieraren dirigerar den till att konvertera alla strängar till Unicode-värden. Modifieraren Auto dirigerar Visual Basic till marskalksträngar enligt .NET Framework-regler baserat på den externa referensen name, eller aliasname om det anges. Standardvärdet är Ansi.

    charsetmodifier anger också hur Visual Basic ska leta upp den externa proceduren i den externa filen. Ansi och Unicode båda dirigerar Visual Basic för att slå upp det utan att ändra dess namn under sökningen. Auto dirigerar Visual Basic till att fastställa basteckenuppsättningen för körningsplattformen och eventuellt ändra namnet på den externa proceduren enligt följande:

    • På en Unicode-plattform, till exempel Windows, letar du först upp den externa proceduren utan namnändring. Om det misslyckas lägger du till "W" i slutet av det externa procedurnamnet och söker upp det igen.

    • På en ANSI-plattform letar du först upp den externa proceduren utan namnändring. Om det misslyckas lägger du till "A" i slutet av det externa procedurnamnet och letar upp det igen.

  • Mekanism. Visual Basic använder mekanismen .NET Framework platform invoke (PInvoke) för att lösa och komma åt externa procedurer. Instruktionen Declare och klassen använder båda den DllImportAttribute här mekanismen automatiskt, och du behöver ingen kunskap om PInvoke. Mer information finns i Genomgång: Anropa Windows-API:er.

Viktigt!

Om den externa proceduren körs utanför CLR (Common Language Runtime) är den ohanterad kod. När du anropar en sådan procedur, till exempel en Windows API-funktion eller en COM-metod, kan du utsätta programmet för säkerhetsrisker. Mer information finns i Riktlinjer för säker kodning för ohanterad kod.

Exempel 1

I följande exempel deklareras en extern referens till en Function procedur som returnerar det aktuella användarnamnet. Den anropar sedan den externa proceduren GetUserNameA som en del av proceduren 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

Exempel 2

Ger DllImportAttribute ett alternativt sätt att använda funktioner i ohanterad kod. I följande exempel deklareras en importerad funktion utan att använda en Declare -instruktion.

' 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

Se även