Declare Statement

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

Comentarios

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 al procedimiento correctamente, como dónde se ubica el procedimiento, cómo se identifica, su secuencia de llamada y el tipo de valor devuelto, y el juego de caracteres de cadena que utiliza. La instrucción Declare crea una referencia a un procedimiento externo y proporciona esta información necesaria.

Solo se puede usar Declare en un nivel de módulo. Esto significa que el contexto de ejecución de una referencia externa debe ser una clase, una estructura o un módulo, y no puede ser un archivo de código fuente, un espacio de nombres, una interfaz, un procedimiento o un bloque. Para obtener más información, vea Declaration Contexts and Default Access Levels (Contextos de declaración y niveles de acceso predeterminados).

De manera predeterminada, el acceso a las referencias externas es público. Los niveles de acceso se pueden ajustar 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 palabra clave Shared al declarar una referencia externa y no puede modificar su estado compartido.

  Un procedimiento externo no puede participar en la invalidación, implementar miembros de interfaz ni controlar eventos. En consecuencia, no puede usar la palabra clave Overrides, Overridable, NotOverridable, MustOverride, Implements o Handles en una instrucción Declare.

• 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 cláusula Alias 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, un 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.

• Nombre del procedimiento externo. De manera alternativa, puede usar una cláusula Alias para especificar el número ordinal del punto de entrada dentro de la tabla de exportación del archivo externo. Para ello, puede comenzar aliasname con un signo numérico (#). Esto puede resultar ú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ámetro. 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. Dentro de parameterlist, se usa una cláusula As 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 preocuparse de que los tipos de datos correspondan. Por ejemplo, si declara una referencia externa a un procedimiento de Visual Basic 6.0 con un parámetro Integer (16 bits en Visual Basic 6.0), debe identificar el argumento correspondiente como Short en la instrucción Declare, ya que es el tipo entero de 16 bits en Visual Basic. De manera similar, Long tiene un ancho de datos distinto en Visual Basic 6.0 y Date se implementa de una manera diferente.

• Tipo de datos devuelto. Si el procedimiento externo es una Function y Option 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 excepción MarshalDirectiveException en tiempo de ejecución.

• Tipos de datos predeterminados. Si Option Strict es Off y no se 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 como Object.

  Nota

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

Comportamiento

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

• Lifetime (Duración). Una referencia externa tiene la misma duración que la clase, la estructura o el módulo en el que se declara.

• Llamada a un procedimiento externo. Se llama a un procedimiento externo del mismo modo que se llama a un procedimiento Function o Sub, mediante su uso en una expresión si devuelve un valor, o bien especificándolo en una instrucción Call si no lo devuelve.

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

• Juegos de caracteres. En charsetmodifier, puede especificar cómo Visual Basic debe serializar las cadenas cuando llama al procedimiento externo. El modificador Ansi indica a Visual Basic serializar todas las cadenas en valores ANSI y el modificador Unicode le indica serializar todas las cadenas en valores Unicode. El modificador Auto indica a Visual Basic serializar todas las cadenas según las reglas de .NET Framework en función de la referencia externa name, 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 ese archivo externo. Ansi y Unicode indica a Visual Basic buscarlo sin modificar el nombre durante la búsqueda. Auto indica a Visual Basic 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 modificar el nombre. Si eso no da resultado, escriba "W" al final del nombre del procedimiento externo y vuelva a buscarlo.

  • En una plataforma ANSI, primero busque el procedimiento externo sin modificar el nombre. Si eso no da resultado, escriba "A" al final del nombre del procedimiento externo y vuelva a buscarlo.

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

Ejemplo 1

En el ejemplo siguiente, se declara una referencia externa a un procedimiento Function que devuelve el nombre de usuario actual. Luego, se llama al procedimiento externo GetUserNameA como parte del procedimiento 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

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 instrucción 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

Consulte también

• LastDllError
• Instrucción Imports (Tipo y espacio de nombres de .NET)
• AddressOf (operador)
• Instrucción Function
• Instrucción Sub
• Lista de parámetros
• Instrucción Call
• Tutorial: Llamadas a las API de Windows