Declare Statement

  • Статья

Объявляет ссылку на процедуру, реализованную во внешнем файле.

Синтаксис

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

Детали

Термин Определение
attributelist Необязательно. См . список атрибутов.
accessmodifier Необязательно. Может применяться один из перечисленных ниже типов.

- Открытый
- Protected
- Friend
- Частное
- Protected Friend
- Private Protected

См. раздел Access levels in Visual Basic.
Shadows Необязательно. См . тени.
charsetmodifier Необязательно. Указывает набор символов и сведения о поиске файлов. Может применяться один из перечисленных ниже типов.

- Ansi (по умолчанию)
- Юникод
- Автоматически
Sub Необязательный, но SubFunction должен отображаться либо. Указывает, что внешняя процедура не возвращает значение.
Function Необязательный, но SubFunction должен отображаться либо. Указывает, что внешняя процедура возвращает значение.
name Обязательный. Имя этой внешней ссылки. Дополнительные сведения см. в разделе "Объявленные имена элементов".
Lib Обязательный. Lib Представляет предложение, определяющее внешний файл (DLL или ресурс кода), содержащий внешнюю процедуру.
libname Обязательный. Имя файла, содержащего объявленную процедуру.
Alias Необязательно. Указывает, что объявленная процедура не может быть определена в файле по имени, указанному в name. Вы указываете его идентификацию в aliasname.
aliasname Требуется, если вы используете Alias ключевое слово. Строка, определяющая процедуру одним из двух способов:

Имя точки входа процедуры в файле в кавычках ("")

–или–

Числовой знак (#), за которым следует целое число, указывающее порядковое число точки входа процедуры в файле.
parameterlist Требуется, если процедура принимает параметры. См . список параметров.
returntype Обязательный параметр, если Function указан и Option Strict имеет значение On. Тип данных значения, возвращаемого процедурой.

Замечания

Иногда необходимо вызвать процедуру, определенную в файле (например, библиотеке DLL или ресурсе кода) за пределами проекта. При этом компилятор Visual Basic не имеет доступа к информации, которую необходимо правильно вызвать процедуру, например, где находится процедура, как она определена, ее последовательность вызовов и тип возвращаемого значения, а также используется строковый символ. Оператор Declare создает ссылку на внешнюю процедуру и предоставляет эти необходимые сведения.

Declare можно использовать только на уровне модуля. Это означает, что контекст объявления для внешней ссылки должен быть классом, структурой или модулем и не может быть исходным файлом, пространством имен, интерфейсом, процедурой или блоком. Дополнительные сведения см. в разделе Контексты объявления и уровни доступа по умолчанию.

Внешние ссылки по умолчанию для общедоступного доступа. Уровни доступа можно настроить с помощью модификаторов доступа.

Правила

  • Атрибуты. Атрибуты можно применить к внешней ссылке. Любой атрибут, который вы применяете, действует только в проекте, а не во внешнем файле.

  • Модификаторы. Внешние процедуры неявно совместно используются. Вы не можете использовать Shared ключевое слово при объявлении внешней ссылки и изменить его общее состояние.

    Внешняя процедура не может участвовать в переопределении, реализации элементов интерфейса или обработке событий. Соответственно, нельзя использовать Overridesоператор , Overridable, NotOverridableImplementsMustOverrideили Handles ключевое слово.Declare

  • Имя внешней процедуры. Вы не должны указывать эту внешнюю ссылку на то же имя (in name), что и имя точки входа процедуры в его внешнем файле (aliasname). Предложение можно использовать Alias для указания имени точки входа. Это может быть полезно, если внешняя процедура имеет то же имя, что и зарезервированный модификатор Visual Basic или переменную, процедуру или любой другой элемент программирования в том же область.

    Примечание.

    Имена точек входа в большинстве БИБЛИОТЕК DLL чувствительны к регистру.

  • Номер внешней процедуры. Кроме того, можно использовать Alias предложение, чтобы указать порядковое число точки входа в таблице экспорта внешнего файла. Для этого начните aliasname с знака номера (#). Это может быть полезно, если любой символ во внешнем имени процедуры не разрешен в Visual Basic или если внешний файл экспортирует процедуру без имени.

Правила типа данных

  • Типы данных параметров. Если Option Strict это Onтак, необходимо указать тип данных каждого параметра в parameterlist. Это может быть любой тип данных или имя перечисления, структуры, класса или интерфейса. В рамках parameterlistпредложения вы используете As предложение для указания типа данных аргумента, передаваемого каждому параметру.

    Примечание.

    Если внешняя процедура не была написана для платформа .NET Framework, необходимо учесть соответствие типов данных. Например, если объявить внешнюю ссылку на процедуру Visual Basic 6.0 с Integer параметром (16 битов в Visual Basic 6.0), необходимо определить соответствующий аргумент, как в Declare инструкции, так как Short это 16-разрядный целочисленный тип в Visual Basic. Long Аналогично, имеет другую ширину данных в Visual Basic 6.0 и Date реализуется по-разному.

  • Возвращаемый тип данных. Если внешняя процедура является и является FunctionOn, Option Strict необходимо указать тип данных значения, возвращаемого вызывающем коду. Это может быть любой тип данных или имя перечисления, структуры, класса или интерфейса.

    Примечание.

    Компилятор Visual Basic не проверяет совместимость типов данных с внешними процедурами. Если имеется несоответствие, среда CLR создает MarshalDirectiveException исключение во время выполнения.

  • Типы данных по умолчанию. Если Option Strict задан Off и не указан тип данных параметра в parameterlist, компилятор Visual Basic преобразует соответствующий аргумент в тип данных объекта. Аналогичным образом, если не указать returntype, компилятор принимает возвращаемый тип Objectданных.

    Примечание.

    Так как вы работаете с внешней процедурой, которая могла быть написана на другой платформе, это опасно сделать любые предположения о типах данных или разрешить им по умолчанию. При наличии гораздо безопаснее указать тип данных каждого параметра и возвращаемого значения. Это также повышает удобочитаемость кода.

Поведение

  • Область. Внешняя ссылка находится в область по всему классу, структуре или модулю.

  • Время существования. Внешняя ссылка имеет то же время существования, что и класс, структура или модуль, в котором он объявлен.

  • Вызов внешней процедуры. Вы вызываете внешнюю процедуру так же, как вызываете Function или Sub процедуру, используя ее в выражении, если он возвращает значение или указывает его в операторе вызова, если он не возвращает значение.

    Аргументы передаются внешней процедуре точно так же, как указано parameterlist в инструкции Declare . Не учитывайте, как параметры были первоначально объявлены во внешнем файле. Аналогичным образом, если имеется возвращаемое значение, используйте его точно так же, как указано returntype в инструкции Declare .

  • Наборы символов. Вы можете указать charsetmodifier , как Visual Basic должен маршалировать строки при вызове внешней процедуры. Модификатор Ansi направляет Visual Basic для маршалирования всех строк в значения ANSI, а Unicode модификатор направляет его для маршалирования всех строк в значения Юникода. Модификатор Auto направляет Visual Basic маршалировать строки в соответствии с правилами платформа .NET Framework на основе внешней ссылки nameилиaliasname, если он указан. Значение по умолчанию — Ansi.

    charsetmodifier также указывает, как Visual Basic должен искать внешнюю процедуру в его внешнем файле. Ansi и Unicode visual Basic, чтобы искать его, не изменяя его имя во время поиска. Auto Позволяет Visual Basic определить базовый набор символов платформы времени выполнения и, возможно, изменить имя внешней процедуры следующим образом:

    • На платформе Юникода, например Windows, сначала просмотрите внешнюю процедуру без изменения имени. Если это не удается, добавьте "W" в конец имени внешней процедуры и снова просмотрите его.

    • На платформе ANSI сначала просмотрите внешнюю процедуру без изменения имени. Если это не удается, добавьте "A" в конец имени внешней процедуры и снова просмотрите его.

  • Механизм. Visual Basic использует механизм вызова платформы платформа .NET Framework (PInvoke) для разрешения и доступа к внешним процедурам. Оператор Declare и DllImportAttribute класс используют этот механизм автоматически, и вам не требуется никаких знаний о PInvoke. Дополнительные сведения см. в пошаговом руководстве. Вызов API Windows.

Внимание

Если внешняя процедура выполняется вне среды CLR, это неуправляемый код. При вызове такой процедуры, например функции API Windows или метода COM, вы можете предоставить приложению риски безопасности. Дополнительные сведения см. в руководстве по безопасному коду для неуправляемого кода.

Пример 1

В следующем примере объявляется внешняя ссылка Function на процедуру, возвращающую текущее имя пользователя. Затем он вызывает внешнюю процедуру GetUserNameA в рамках 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

Пример 2

Предоставляет DllImportAttribute альтернативный способ использования функций в неуправляемом коде. В следующем примере объявляется импортированная функция без использования инструкции 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

См. также