Declare — Instrukcja

Deklaruje odwołanie do procedury zaimplementowanej w pliku zewnętrznym.

Składnia

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

generatora

Termin	Definicja
attributelist	Opcjonalny. Zobacz Lista atrybutów.
accessmodifier	Opcjonalny. Może być jednym z następujących elementów: - Public - Protected - Friend - Private - Protected Friend - Private Protected Zobacz Poziomy dostępu w Visual Basic.
Shadows	Opcjonalny. Zobacz Cienie.
charsetmodifier	Opcjonalny. Określa zestaw znaków i informacje o wyszukiwaniu plików. Może być jednym z następujących elementów: - Ansi (ustawienie domyślne) - Unicode - Auto
Sub	Opcjonalnie, ale musi pojawić się element Sub lub Function . Wskazuje, że procedura zewnętrzna nie zwraca wartości.
Function	Opcjonalnie, ale musi pojawić się element Sub lub Function . Wskazuje, że procedura zewnętrzna zwraca wartość.
name	Wymagany. Nazwa tego odwołania zewnętrznego. Aby uzyskać więcej informacji, zobacz Deklarowane nazwy elementów.
Lib	Wymagany. Wprowadza klauzulę Lib , która identyfikuje plik zewnętrzny (dll lub zasób kodu), który zawiera procedurę zewnętrzną.
libname	Wymagany. Nazwa pliku zawierającego zadeklarowaną procedurę.
Alias	Opcjonalny. Wskazuje, że zadeklarowana procedura nie może być zidentyfikowana w pliku przez nazwę określoną w namepliku . Należy określić jego identyfikację w pliku aliasname.
aliasname	Wymagane, jeśli używasz słowa kluczowego Alias . Ciąg identyfikujący procedurę na jeden z dwóch sposobów: Nazwa punktu wejścia procedury w pliku w cudzysłowie ("") — lub — Znak numeru (#), po którym następuje liczba całkowita określająca liczbę porządkową punktu wejścia procedury w pliku
parameterlist	Wymagane, jeśli procedura przyjmuje parametry. Zobacz Lista parametrów.
returntype	Wymagane, jeśli Function jest określony i Option Strict ma wartość On. Typ danych wartości zwracanej przez procedurę.

Uwagi

Czasami należy wywołać procedurę zdefiniowaną w pliku (takim jak biblioteka DLL lub zasób kodu) poza projektem. Gdy to zrobisz, kompilator języka Visual Basic nie ma dostępu do informacji potrzebnych do poprawnego wywołania procedury, takich jak miejsce, w którym znajduje się procedura, sposób jego identyfikacji, jego sekwencja wywołania i typ zwracany oraz zestaw znaków ciągu, którego używa. Instrukcja Declare tworzy odwołanie do procedury zewnętrznej i dostarcza te niezbędne informacje.

Można używać Declare tylko na poziomie modułu. Oznacza to, że kontekst deklaracji odwołania zewnętrznego musi być klasą, strukturą lub modułem i nie może być plikiem źródłowym, przestrzenią nazw, interfejsem, procedurą lub blokiem. Aby uzyskać więcej informacji, zobacz Konteksty deklaracji i Domyślne poziomy dostępu.

Odwołania zewnętrzne domyślnie mają dostęp publiczny . Możesz dostosować ich poziomy dostępu za pomocą modyfikatorów dostępu.

Reguły

• Atrybuty. Atrybuty można zastosować do odwołania zewnętrznego. Każdy zastosowany atrybut ma wpływ tylko w projekcie, a nie w pliku zewnętrznym.

• Modyfikatorów. Procedury zewnętrzne są niejawnie udostępniane. Nie można użyć Shared słowa kluczowego podczas deklarowania odwołania zewnętrznego i nie można zmienić jego stanu udostępnionego.

  Procedura zewnętrzna nie może uczestniczyć w zastępowaniu, implementowaniu elementów członkowskich interfejsu ani obsłudze zdarzeń. W związku z tym nie można użyć słowa kluczowego Overrides, Overridable, NotOverridable, MustOverride, Implementslub Handles w instrukcji Declare .

• Nazwa procedury zewnętrznej. Nie musisz podawać tego odwołania zewnętrznego o tej samej nazwie (w ), nameco nazwa punktu wejścia procedury w jego pliku zewnętrznym (aliasname). Możesz użyć klauzuli Alias , aby określić nazwę punktu wejścia. Może to być przydatne, jeśli procedura zewnętrzna ma taką samą nazwę jak modyfikator zarezerwowany języka Visual Basic lub zmienna, procedura lub dowolny inny element programowania w tym samym zakresie.

  Uwaga

  Nazwy punktów wejścia w większości bibliotek DLL są uwzględniane wielkości liter.

• Numer procedury zewnętrznej. Alternatywnie można użyć Alias klauzuli , aby określić liczbę porządkową punktu wejścia w tabeli eksportu pliku zewnętrznego. W tym celu zaczynasz od aliasname znaku numeru (#). Może to być przydatne, jeśli dowolny znak w nazwie procedury zewnętrznej nie jest dozwolony w Visual Basic lub jeśli plik zewnętrzny eksportuje procedurę bez nazwy.

Reguły typów danych

• Typy danych parametrów. Jeśli Option Strict parametr ma Onwartość , należy określić typ danych każdego parametru w pliku parameterlist. Może to być dowolny typ danych lub nazwa wyliczenia, struktury, klasy lub interfejsu. W programie parameterlistnależy użyć As klauzuli , aby określić typ danych argumentu, który ma zostać przekazany do każdego parametru.

  Uwaga

  Jeśli procedura zewnętrzna nie została napisana dla programu .NET Framework, należy zadbać o to, aby typy danych były zgodne. Jeśli na przykład zadeklarujesz odwołanie zewnętrzne do procedury visual Basic 6.0 z parametrem Integer (16 bitów w visual basic 6.0), musisz zidentyfikować odpowiedni argument w ShortDeclare instrukcji , ponieważ jest to 16-bitowy typ całkowity w Visual Basic. Podobnie ma Long inną szerokość danych w języku Visual Basic 6.0 i Date jest implementowana inaczej.

• Zwracanie typu danych. Jeśli procedura zewnętrzna to Function i Option Strict , Onnależy określić typ danych wartości zwróconej do kodu wywołującego. Może to być dowolny typ danych lub nazwa wyliczenia, struktury, klasy lub interfejsu.

  Uwaga

  Kompilator języka Visual Basic nie sprawdza, czy typy danych są zgodne z typami procedur zewnętrznych. Jeśli występuje niezgodność, środowisko uruchomieniowe języka wspólnego generuje MarshalDirectiveException wyjątek w czasie wykonywania.

• Domyślne typy danych. Jeśli Option Strict parametr ma wartość i Off nie określisz typu danych w programie parameterlist, kompilator języka Visual Basic konwertuje odpowiedni argument na typ danych obiektu. Podobnie, jeśli nie określisz returntypeparametru , kompilator przyjmuje zwracany typ danych na Objectwartość .

  Uwaga

  Ponieważ masz do czynienia z procedurą zewnętrzną, która mogła zostać napisana na innej platformie, niebezpieczne jest wprowadzenie wszelkich założeń dotyczących typów danych lub zezwolenie na ich domyślne użycie. Znacznie bezpieczniejsze jest określenie typu danych każdego parametru i wartości zwracanej, jeśli istnieje. Zwiększa to również czytelność kodu.

Zachowanie

• Zakres. Odwołanie zewnętrzne znajduje się w zakresie w całej swojej klasie, strukturze lub module.

• Okres istnienia. Odwołanie zewnętrzne ma taki sam okres istnienia jak klasa, struktura lub moduł, w którym jest zadeklarowany.

• Wywoływanie procedury zewnętrznej. Wywołaj procedurę zewnętrzną w taki sam sposób, jak wywołasz procedurę Function lub Sub , używając jej w wyrażeniu, jeśli zwraca wartość, lub określając ją w instrukcji Call, jeśli nie zwraca wartości.

  Argumenty są przekazywane do procedury zewnętrznej dokładnie tak, jak określono parameterlist w instrukcji Declare . Nie należy uwzględniać sposobu, w jaki parametry zostały pierwotnie zadeklarowane w pliku zewnętrznym. Podobnie, jeśli istnieje wartość zwracana, użyj jej dokładnie tak, jak określono returntype w instrukcji Declare .

• Zestawy znaków. Możesz określić sposób, w charsetmodifier jaki visual basic powinien marshalować ciągi, gdy wywołuje procedurę zewnętrzną. Modyfikator Ansi przekierowuje program Visual Basic do marshalingu wszystkich ciągów do wartości ANSI, a Unicode modyfikator kieruje go do marshalingu wszystkich ciągów do wartości Unicode. Modyfikator Auto przekierowuje program Visual Basic do marshalingu ciągów zgodnie z regułami programu .NET Framework na podstawie odwołania namezewnętrznego lub aliasname , jeśli określono. Domyślna wartość to Ansi.

  charsetmodifier Określa również, jak program Visual Basic powinien wyszukać procedurę zewnętrzną w pliku zewnętrznym. Ansi i Unicode zarówno direct Visual Basic, aby wyszukać go bez modyfikowania jego nazwy podczas wyszukiwania. Auto Program Visual Basic kieruje program Visual Basic do określenia podstawowego zestawu znaków platformy czasu wykonywania i ewentualnie zmodyfikowania nazwy procedury zewnętrznej w następujący sposób:

  • Na platformie Unicode, takiej jak Windows, najpierw wyszukaj procedurę zewnętrzną bez modyfikacji nazwy. Jeśli to się nie powiedzie, dołącz ciąg "W" na końcu nazwy procedury zewnętrznej i wyszukaj go ponownie.

  • Na platformie ANSI najpierw wyszukaj procedurę zewnętrzną bez modyfikacji nazwy. Jeśli to się nie powiedzie, dołącz ciąg "A" na końcu nazwy procedury zewnętrznej i wyszukaj go ponownie.

• Mechanizm. Program Visual Basic używa mechanizmu wywołania platformy .NET Framework (PInvoke) w celu rozpoznawania procedur zewnętrznych i uzyskiwania do niego dostępu. Instrukcja Declare i DllImportAttribute klasa używają tego mechanizmu automatycznie i nie potrzebujesz żadnej wiedzy na temat funkcji PInvoke. Aby uzyskać więcej informacji, zobacz Przewodnik: wywoływanie interfejsów API systemu Windows.

Ważne

Jeśli procedura zewnętrzna jest uruchamiana poza środowiskiem uruchomieniowym języka wspólnego (CLR), jest to kod niezarządzany. Wywołanie takiej procedury, na przykład funkcji interfejsu API systemu Windows lub metody COM, może spowodować narażenie aplikacji na zagrożenia bezpieczeństwa. Aby uzyskać więcej informacji, zobacz Secure Coding Guidelines for Unmanaged Code (Wytyczne dotyczące bezpiecznego kodowania dla niezarządzanych kodów).

Przykład 1

Poniższy przykład deklaruje zewnętrzne odwołanie do procedury zwracającej bieżącą Function nazwę użytkownika. Następnie wywołuje procedurę GetUserNameA zewnętrzną w ramach getUser procedury.

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

Przykład 2

Zapewnia DllImportAttribute alternatywny sposób używania funkcji w kodzie niezarządzanym. Poniższy przykład deklaruje zaimportowaną funkcję bez użycia instrukcji 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

Zobacz też

• LastDllError
• Imports, instrukcja (przestrzeń nazw i typ .NET)
• AddressOf, operator
• Function, instrukcja
• Sub, instrukcja
• Lista parametrów
• Call, instrukcja
• Przewodnik: wywoływanie interfejsów API systemu Windows