Оператор Declare

Статья
04/10/2013

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

[ <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	Необязательный.Может принимать следующие значения: Открытый Защищенный Friend Закрытый Protected Friend Дополнительные сведения см. в разделе Уровни доступа в Visual Basic.
Shadows	Необязательный.См. раздел Shadows.
charsetmodifier	Необязательный.Задает кодировку и информацию для поиска файла.Может принимать следующие значения: Ansi (Visual Basic) (по умолчанию) Юникод (Visual Basic) Auto (Visual Basic)
Sub	Необязательно, но требуется наличие Sub или Function.Указывает на то, что внешняя процедура не возвращает значение.
Function	Необязательно, но требуется наличие Sub или Function.Указывает на то, что внешняя процедура возвращает значение.
name	Обязательный.Имя этой внешней ссылки.Дополнительные сведения см. в разделе Имена объявленных типов (Visual Basic).
Lib	Обязательный.Вводит предложение Lib, которое определяет внешний файл (библиотека DLL или источник кода), содержащий внешнюю процедуру.
libname	Обязательный.Имя файла, который содержит объявляемую процедуру.
Alias	Необязательный.Указывает, что объявляемая процедура не может быть идентифицирована в ее файле по имени, указанному в name.Необходимо указать его идентификацию в aliasname.
aliasname	Является обязательным, если используется ключевое слово Alias.Строка, идентифицирующая процедуру одним из двух способов: Имя точки входа в процедуру в файле в кавычках ("") -или- Символ решетки (#), за которым следует целое число, указывающее порядковый номер точки входа в процедуру в файле
parameterlist	Требуется, если процедура принимает параметры.Дополнительные сведения см. в разделе Список параметров (Visual Basic).
returntype	Требуется, если указана инструкция Function, а Option Strict имеет значение On.Тип значения, возвращаемого процедурой.

Заметки

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

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

Внешние ссылки по умолчанию имеют уровень доступа Public (Visual Basic).Уровни доступа можно настроить с помощью модификаторов доступа.

Правила

Атрибуты. Можно применить атрибуты к внешней ссылке.Любой применяемый атрибут имеет силу только в проекте, а не во внешнем файле.
Модификаторы. Внешние процедуры неявно являются Shared (Visual Basic).Нельзя использовать ключевое слово Shared при объявлении внешней ссылки и невозможно изменить ее статус общего доступа.

Внешняя процедура не может участвовать в переопределении, реализовывать члены интерфейса или обрабатывать события.Соответственно в операторе Declare нельзя использовать Overrides, Overridable, NotOverridable, MustOverride, Implements или Handles.
Имя внешней процедуры. Нет необходимости задавать этой внешней ссылке такое же имя (в name), как имя точки входа в процедуру во внешнем файле (aliasname).Оператор Alias можно использовать для указания имени точки входа.Это может быть полезно, если внешняя процедура имеет такое же имя, как зарезервированный модификатор Visual Basic, переменная, процедура или любой другой элемент программирования в той же самой области видимости.

Примечание

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

Примечание
В большинстве DLL имена точек входа зависят от регистра.

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

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

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

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

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

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

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

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

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

Поведение

Область действия. Область внешней ссылки - ее класс, структура или модуль.
Время существования. Внешняя ссылка имеет такое же время жизни, как класс, структура или модуль, в котором она была объявлена.
Вызов внешних процедур. Вызов внешней процедуры производится таким же образом, как и вызов Function или Sub процедуры — с помощью использования ее в выражении, если она возвращает значение, или с помощью указания ее в Оператор Call (Visual Basic), если она не возвращает значения.

Аргументы передаются внешней процедуре точно в соответствии с 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 определить базовую кодировку платформы времени выполнения и, возможно, изменить имя внешней процедуры следующим образом:
- На ANSI платформах, таких как Windows 95, Windows 98 или Windows Millennium Edition, сначала производится поиск внешней процедуры без изменения имени.В случае неудачи в конец имени внешней процедуры добавляется "A", и осуществляется повторный поиск.
- На Юникод платформе, таких как Windows NT, Windows 2000 или Windows XP, сначала производится поиск внешней процедуры без изменения имени.В случае неудачи в конец имени внешней процедуры добавляется "W", и осуществляется повторный поиск.
Механизм. Visual Basic использует механизм .NET Framework платформозависимый вызов (PInvoke) для разрешения и доступа к внешним процедурам.Инструкция Declare и класс DllImportAttribute используют этот механизм автоматически и не нуждаются в любых знаниях о PInvoke.Дополнительные сведения см. в разделе Пошаговое руководство. Вызов API Windows (Visual Basic).

Примечание по безопасности
Если внешняя процедура выполняется за пределами общеязыковой среды выполнения (CLR), то это неуправляемый код.При вызове таких процедур, например функции Win32 API или метода COM, приложение может подвергаться угрозе безопасности.Дополнительные сведения см. в разделе Неуправляемый код.

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

Пример

В следующем примере объявляется внешняя ссылка на 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

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