Compartir a través de

Declare (instrucción)

Declara una referencia a un procedimiento implementado en un archivo externo.

Sintaxis

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

Partes

Término Definición
attributelist Opcional. Consulte Lista de atributos.
accessmodifier Opcional. Puede ser uno de los siguientes:

- Público
- Protegido
- Amigo
- Privado
- Amigo protegido
- Protegido privado

Consulte Niveles de acceso en Visual Basic.
Shadows Opcional. Vea Sombras.
charsetmodifier Opcional. Especifica el juego de caracteres y la información de búsqueda de archivos. Puede ser uno de los siguientes:

- Ansi (valor predeterminado)
- Unicode
- Automático
Sub Opcional, pero debe aparecer o SubFunction . Indica que el procedimiento externo no devuelve un valor.
Function Opcional, pero debe aparecer o SubFunction . Indica que el procedimiento externo devuelve un valor.
name Obligatorio. Nombre de esta referencia externa. Para obtener más información, vea Nombres de elementos declarados.
Lib Obligatorio. Presenta una Lib cláusula , que identifica el archivo externo (archivo DLL o recurso de código) que contiene un procedimiento externo.
libname Obligatorio. Nombre del archivo que contiene el procedimiento declarado.
Alias Opcional. Indica que el procedimiento que se declara no se puede identificar dentro de su archivo por el nombre especificado en name. Especifique su identificación en aliasname.
aliasname Obligatorio si usa la Alias palabra clave . Cadena que identifica el procedimiento de una de estas dos maneras:

Nombre de punto de entrada del procedimiento dentro de su archivo, entre comillas ("")

-o-

Signo de número (#) seguido de un entero que especifica el número ordinal del punto de entrada del procedimiento dentro de su archivo
parameterlist Obligatorio si el procedimiento toma parámetros. Consulte Lista de parámetros.
returntype Obligatorio si Function se especifica y Option Strict es On. Tipo de datos del valor devuelto por el procedimiento.

Observaciones

A veces, debe llamar a un procedimiento definido en un archivo (como un archivo DLL o un recurso de código) fuera del proyecto. Al hacerlo, el compilador de Visual Basic no tiene acceso a la información que necesita para llamar correctamente al procedimiento, como dónde se encuentra el procedimiento, cómo se identifica, su secuencia de llamada y el tipo de valor devuelto, y el juego de caracteres de cadena que usa. La Declare instrucción crea una referencia a un procedimiento externo y proporciona esta información necesaria.

Solo puede usar Declare en el nivel de módulo. Esto significa que el contexto de declaración de una referencia externa debe ser una clase, estructura o módulo, y no puede ser un archivo de origen, espacio de nombres, interfaz, procedimiento o bloque. Para obtener más información, vea Contextos de declaración y Niveles de acceso predeterminados.

Las referencias externas tienen como valor predeterminado acceso público . Puede ajustar sus niveles de acceso con los modificadores de acceso.

Reglas

  • Atributos. Puede aplicar atributos a una referencia externa. Cualquier atributo que aplique solo tiene efecto en el proyecto, no en el archivo externo.

  • Modificadores. Los procedimientos externos se comparten implícitamente. No puede usar la Shared palabra clave al declarar una referencia externa y no puede modificar su estado compartido.

    Un procedimiento externo no puede participar en la invalidación, implementación de miembros de interfaz ni control de eventos. En consecuencia, no puede usar la Overridespalabra clave , Overridable, NotOverridable, MustOverride, Implementso Handles en una Declare instrucción .

  • Nombre del procedimiento externo. No es necesario asignar a esta referencia externa el mismo nombre (en name) que el nombre del punto de entrada del procedimiento dentro de su archivo externo (aliasname). Puede usar una Alias cláusula para especificar el nombre del punto de entrada. Esto puede ser útil si el procedimiento externo tiene el mismo nombre que un modificador reservado de Visual Basic o una variable, procedimiento o cualquier otro elemento de programación en el mismo ámbito.

    Nota:

    Los nombres de punto de entrada en la mayoría de los archivos DLL distinguen mayúsculas de minúsculas.

  • Número de procedimiento externo. Como alternativa, puede usar una Alias cláusula para especificar el número ordinal del punto de entrada dentro de la tabla de exportación del archivo externo. Para ello, comience aliasname con un signo de número (#). Esto puede ser útil si no se permite ningún carácter en el nombre del procedimiento externo en Visual Basic o si el archivo externo exporta el procedimiento sin un nombre.

Reglas de tipo de datos

  • Tipos de datos de parámetros. Si Option Strict es On, debe especificar el tipo de datos de cada parámetro en parameterlist. Puede ser cualquier tipo de datos o el nombre de una enumeración, estructura, clase o interfaz. En parameterlist, se usa una As cláusula para especificar el tipo de datos del argumento que se va a pasar a cada parámetro.

    Nota:

    Si el procedimiento externo no se escribió para .NET Framework, debe tener cuidado de que los tipos de datos correspondan. Por ejemplo, si declara una referencia externa a un procedimiento de Visual Basic 6.0 con un Integer parámetro (16 bits en Visual Basic 6.0), debe identificar el argumento correspondiente como Short en la Declare instrucción , ya que es el tipo entero de 16 bits en Visual Basic. Del mismo modo, Long tiene un ancho de datos diferente en Visual Basic 6.0 y Date se implementa de forma diferente.

  • Tipo de datos devuelto. Si el procedimiento externo es y FunctionOption Strict es On, debe especificar el tipo de datos del valor devuelto al código de llamada. Puede ser cualquier tipo de datos o el nombre de una enumeración, estructura, clase o interfaz.

    Nota:

    El compilador de Visual Basic no comprueba que los tipos de datos sean compatibles con los del procedimiento externo. Si hay un error de coincidencia, Common Language Runtime genera una MarshalDirectiveException excepción en tiempo de ejecución.

  • Tipos de datos predeterminados. Si Option Strict es Off y no especifica el tipo de datos de un parámetro en parameterlist, el compilador de Visual Basic convierte el argumento correspondiente en el tipo de datos object. Del mismo modo, si no especifica returntype, el compilador toma el tipo de datos devuelto para que sea Object.

    Nota:

    Dado que está tratando con un procedimiento externo que podría haberse escrito en una plataforma diferente, es peligroso realizar cualquier suposición sobre los tipos de datos o permitirles el valor predeterminado. Es mucho más seguro especificar el tipo de datos de cada parámetro y del valor devuelto, si existe. Esto también mejora la legibilidad del código.

Comportamiento

  • Ámbito. Una referencia externa está en el ámbito a lo largo de su clase, estructura o módulo.

  • Toda la vida. Una referencia externa tiene la misma duración que la clase, estructura o módulo en el que se declara.

  • Llamar a un procedimiento externo. Se llama a un procedimiento externo de la misma manera que se llama a un Function procedimiento o Sub , mediante su uso en una expresión si devuelve un valor o si lo especifica en una instrucción call si no devuelve un valor.

    Los argumentos se pasan al procedimiento externo exactamente como se especifica en parameterlist la Declare instrucción . No tenga en cuenta cómo se declararon originalmente los parámetros en el archivo externo. De forma similar, si hay un valor devuelto, úselo exactamente como se especifica en returntype la Declare instrucción .

  • Juegos de caracteres. Puede especificar en charsetmodifier cómo Visual Basic debe serializar las cadenas cuando llama al procedimiento externo. El Ansi modificador dirige Visual Basic para serializar todas las cadenas a valores ANSI y el Unicode modificador lo dirige para serializar todas las cadenas a valores Unicode. El Auto modificador dirige a Visual Basic para serializar cadenas según las reglas de .NET Framework basadas en la referencia nameexterna, o aliasname si se especifica. El valor predeterminado es Ansi.

    charsetmodifier especifica también cómo Visual Basic debe buscar el procedimiento externo dentro de su archivo externo. Ansi y Unicode ambos dirigen Visual Basic para buscarlo sin modificar su nombre durante la búsqueda. Auto dirige Visual Basic para determinar el juego de caracteres base de la plataforma en tiempo de ejecución y, posiblemente, modificar el nombre del procedimiento externo, como se indica a continuación:

    • En una plataforma Unicode, como Windows, primero busque el procedimiento externo sin modificaciones de nombre. Si se produce un error, anexe "W" al final del nombre del procedimiento externo y vuelva a buscarlo.

    • En una plataforma ANSI, busque primero el procedimiento externo sin modificaciones de nombre. Si se produce un error, anexe "A" al final del nombre del procedimiento externo y vuelva a buscarlo.

  • Mecanismo. Visual Basic usa el mecanismo de invocación de la plataforma .NET Framework (PInvoke) para resolver y acceder a procedimientos externos. La Declare instrucción y la DllImportAttribute clase usan este mecanismo automáticamente y no necesita ningún conocimiento de PInvoke. Para obtener más información, consulte Tutorial: Llamar a las API de Windows.

Importante

Si el procedimiento externo se ejecuta fuera de Common Language Runtime (CLR), es código no administrado. Al llamar a este procedimiento, por ejemplo, una función de API de Windows o un método COM, es posible que exponga la aplicación a riesgos de seguridad. Para obtener más información, vea Instrucciones de codificación segura para código no administrado.

Ejemplo 1

En el ejemplo siguiente se declara una referencia externa a un Function procedimiento que devuelve el nombre de usuario actual. A continuación, llama al procedimiento GetUserNameA externo como parte del getUser procedimiento.

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

Ejemplo 2

DllImportAttribute proporciona una manera alternativa de usar funciones en código no administrado. En el ejemplo siguiente se declara una función importada sin usar una Declare instrucción .

' 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

Consulte también

  • Last updated on