Оператор Declare

Статья
11/05/2008

Обновлен: Ноябрь 2007

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

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

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

либо

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

Заметки

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

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

Внешние ссылки по умолчанию имеют уровень доступа 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.

Примечание о безопасности.
Если внешняя процедура выполняется за пределами общеязыковой среды выполнения (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

См. также

Оператор Declare

Компоненты

Заметки

Правила

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

Поведение

Пример

См. также

Задачи

Основные понятия

Ссылки

Дополнительные ресурсы