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 es necesario 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 se puede usar Declare en un 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 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).

Las referencias externas tienen como valor predeterminado acceso 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 son compartidos 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, implementar miembros de interfaz ni controlar eventos. En consecuencia, no puede usar la palabra clave Overrides , , , , o en una instrucción Overridable NotOverridable MustOverride Implements Handles Declare .

• Nombre del procedimiento externo. No es necesario dar a esta referencia externa el mismo nombre (en ) que el nombre del punto de entrada del procedimiento dentro de name 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, 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.

• Número de procedimiento externo. Como alternativa, puede usar una cláusula para especificar el número ordinal del punto de entrada dentro de la tabla Alias de exportación del archivo externo. Para ello, comience con aliasname 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 , debe especificar el tipo de datos de cada parámetro en On parameterlist . Puede ser cualquier tipo de datos o el nombre de una enumeración, estructura, clase o interfaz. En , se usa una cláusula para especificar el tipo de datos del argumento que parameterlist se va a pasar a cada As parámetro.

  Nota

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

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

  Nota

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

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

  Nota

  Dado que está trabajando con un procedimiento externo que podría haber sido escrito en una plataforma diferente, es peligroso realizar suposiciones sobre los tipos de datos o permitir que se realicen de forma predeterminada. 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.

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

• Llamar a un procedimiento externo. Se llama a un procedimiento externo de la misma manera que se llama a un procedimiento o ; se usa en una expresión si devuelve un valor o se especifica en una instrucción Call si no devuelve Function Sub un valor.

  Los argumentos se pasan al procedimiento externo exactamente como se especifica en parameterlist la Declare instrucción . No tiene 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 cómo charsetmodifier se Visual Basic serializar cadenas cuando llama al procedimiento externo. El modificador dirige Visual Basic serializar todas las cadenas a valores ANSI y el modificador lo dirige para serializar todas las cadenas a Ansi Unicode valores Unicode. El modificador indica a Visual Basic serializar cadenas según las .NET Framework basadas en la referencia externa Auto name o si se aliasname especifica. El valor predeterminado es Ansi.

  charsetmodifiertambién especifica cómo Visual Basic buscar el procedimiento externo dentro de su archivo externo. Ansiy Unicode dirigen Visual Basic buscarlo sin modificar su nombre durante la búsqueda. Autodirige 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 muestra a continuación:

  • En una plataforma Unicode, como Windows, primero busque el procedimiento externo sin modificar el nombre. Si se produce un error, anexe "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 se produce un error, anexe "A" al final del nombre del procedimiento externo y vuelva a buscarlo.

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

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

proporciona DllImportAttribute 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

Consulta 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