Tutorial: Llamar a las API de Windows (Visual Basic)Walkthrough: Calling Windows APIs (Visual Basic)

Las API de Windows son bibliotecas de vínculos dinámicos (dll) que forman parte del sistema operativo Windows.Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows operating system. Se usan para realizar tareas cuando es difícil escribir procedimientos equivalentes propios.You use them to perform tasks when it is difficult to write equivalent procedures of your own. Por ejemplo, Windows proporciona una función denominada FlashWindowEx que le permite hacer que la barra de título de una aplicación alterne entre sombras claras y oscuras.For example, Windows provides a function named FlashWindowEx that lets you make the title bar for an application alternate between light and dark shades.

La ventaja de usar las API de Windows en el código es que pueden ahorrar tiempo de desarrollo porque contienen docenas de funciones útiles que ya están escritas y en espera de usarse.The advantage of using Windows APIs in your code is that they can save development time because they contain dozens of useful functions that are already written and waiting to be used. El inconveniente es que las API de Windows pueden ser difíciles de trabajar con y Unforgiving cuando hay algún problema.The disadvantage is that Windows APIs can be difficult to work with and unforgiving when things go wrong.

Las API de Windows representan una categoría especial de interoperabilidad.Windows APIs represent a special category of interoperability. Las API de Windows no usan código administrado, no tienen bibliotecas de tipos integrados y usan tipos de datos que son diferentes de los que se usan con Visual Studio.Windows APIs do not use managed code, do not have built-in type libraries, and use data types that are different than those used with Visual Studio. Debido a estas diferencias, y dado que las API de Windows no son objetos COM, la interoperabilidad con las API de Windows y el .NET Framework se realiza mediante la invocación de plataforma o PInvoke.Because of these differences, and because Windows APIs are not COM objects, interoperability with Windows APIs and the .NET Framework is performed using platform invoke, or PInvoke. La invocación de plataforma es un servicio que permite al código administrado llamar a funciones no administradas implementadas en archivos dll.Platform invoke is a service that enables managed code to call unmanaged functions implemented in DLLs. Para obtener más información, vea consumir funciones dll no administradas.For more information, see Consuming Unmanaged DLL Functions. Puede usar PInvoke en Visual Basic mediante la Declare instrucción o aplicando el DllImport atributo a un procedimiento vacío.You can use PInvoke in Visual Basic by using either the Declare statement or applying the DllImport attribute to an empty procedure.

Las llamadas a la API de Windows eran una parte importante de la programación de Visual Basic en el pasado, pero rara vez son necesarias con Visual Basic .NET.Windows API calls were an important part of Visual Basic programming in the past, but are seldom necessary with Visual Basic .NET. Siempre que sea posible, debe usar código administrado desde el .NET Framework para realizar tareas, en lugar de llamadas a la API de Windows.Whenever possible, you should use managed code from the .NET Framework to perform tasks, instead of Windows API calls. En este tutorial se proporciona información sobre las situaciones en las que es necesario usar las API de Windows.This walkthrough provides information for those situations in which using Windows APIs is necessary.

Nota

Es posible que tu equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las siguientes instrucciones.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos.The Visual Studio edition that you have and the settings that you use determine these elements. Para obtener más información, vea Personalizar el IDE.For more information, see Personalizing the IDE.

Llamadas API mediante declareAPI Calls Using Declare

La forma más común de llamar a las API de Windows es Declare mediante la instrucción.The most common way to call Windows APIs is by using the Declare statement.

Para declarar un procedimiento DLLTo declare a DLL procedure

  1. Determine el nombre de la función a la que desea llamar, además de sus argumentos, tipos de argumentos y valor devuelto, así como el nombre y la ubicación del archivo DLL que lo contiene.Determine the name of the function you want to call, plus its arguments, argument types, and return value, as well as the name and location of the DLL that contains it.

    Nota

    Para obtener información completa sobre las API de Windows, consulte la documentación del SDK de Win32 en la API de Windows de Platform SDK.For complete information about the Windows APIs, see the Win32 SDK documentation in the Platform SDK Windows API. Para obtener más información sobre las constantes que usan las API de Windows, examine los archivos de encabezado como Windows. h incluido con el SDK de la plataforma.For more information about the constants that Windows APIs use, examine the header files such as Windows.h included with the Platform SDK.

  2. Abra un nuevo proyecto de aplicación para Windows; para ello, haga clic en nuevo en el menú archivo y, a continuación, haga clic en proyecto.Open a new Windows Application project by clicking New on the File menu, and then clicking Project. Aparecerá el cuadro de diálogo Nuevo proyecto .The New Project dialog box appears.

  3. Seleccione aplicación de Windows en la lista de plantillas de proyecto de Visual Basic.Select Windows Application from the list of Visual Basic project templates. Se muestra el nuevo proyecto.The new project is displayed.

  4. Agregue la siguiente Declare función a la clase o módulo en el que desea utilizar el archivo dll:Add the following Declare function either to the class or module in which you want to use the DLL:

    Declare Auto Function MBox Lib "user32.dll" Alias "MessageBox" (
        ByVal hWnd As Integer,
        ByVal txt As String,
        ByVal caption As String,
        ByVal Typ As Integer) As Integer
    

Partes de la instrucción DeclareParts of the Declare Statement

La Declare instrucción incluye los siguientes elementos.The Declare statement includes the following elements.

Auto (modificador)Auto modifier

El Auto modificador indica al tiempo de ejecución que convierta la cadena basándose en el nombre del método de acuerdo con las reglas de Common Language Runtime (o el nombre de alias si se especifica).The Auto modifier instructs the runtime to convert the string based on the method name according to common language runtime rules (or alias name if specified).

Palabras clave lib y aliasLib and Alias keywords

El nombre que sigue Function a la palabra clave es el nombre que usa el programa para tener acceso a la función importada.The name following the Function keyword is the name your program uses to access the imported function. Puede ser el mismo nombre real de la función a la que se está llamando, o bien se puede usar cualquier nombre de procedimiento válido y, Alias a continuación, utilizar la palabra clave para especificar el nombre real de la función a la que se está llamando.It can be the same as the real name of the function you are calling, or you can use any valid procedure name and then employ the Alias keyword to specify the real name of the function you are calling.

Especifique la Lib palabra clave, seguida del nombre y la ubicación del archivo DLL que contiene la función a la que llama.Specify the Lib keyword, followed by the name and location of the DLL that contains the function you are calling. No es necesario especificar la ruta de acceso de los archivos que se encuentran en los directorios del sistema de Windows.You do not need to specify the path for files located in the Windows system directories.

Use la Alias palabra clave si el nombre de la función a la que se está llamando no es un nombre de procedimiento Visual Basic válido o está en conflicto con el nombre de otros elementos de la aplicación.Use the Alias keyword if the name of the function you are calling is not a valid Visual Basic procedure name, or conflicts with the name of other items in your application. Aliasindica el nombre real de la función que se va a llamar.Alias indicates the true name of the function being called.

Declaraciones de argumentos y tipos de datosArgument and Data Type Declarations

Declare los argumentos y sus tipos de datos.Declare the arguments and their data types. Esta parte puede ser desafiante, ya que los tipos de datos que usa Windows no se corresponden con los tipos de datos de Visual Studio.This part can be challenging because the data types that Windows uses do not correspond to Visual Studio data types. Visual Basic realiza una gran cantidad de trabajo mediante la conversión de argumentos en tipos de datos compatibles, un proceso denominado serialización.Visual Basic does a lot of the work for you by converting arguments to compatible data types, a process called marshaling. Puede controlar explícitamente cómo se calculan las referencias de los MarshalAsAttribute argumentos mediante el atributo System.Runtime.InteropServices definido en el espacio de nombres.You can explicitly control how arguments are marshaled by using the MarshalAsAttribute attribute defined in the System.Runtime.InteropServices namespace.

Nota

Las versiones anteriores de Visual Basic permitían declarar parámetros As Any, lo que significa que se pueden usar datos de cualquier tipo de datos.Previous versions of Visual Basic allowed you to declare parameters As Any, meaning that data of any data type could be used. Visual Basic requiere que se use un tipo de datos específico para Declare todas las instrucciones.Visual Basic requires that you use a specific data type for all Declare statements.

Constantes de la API de WindowsWindows API Constants

Algunos argumentos son combinaciones de constantes.Some arguments are combinations of constants. Por ejemplo, la MessageBox API mostrada en este tutorial acepta un argumento de entero Typ denominado que controla cómo se muestra el cuadro de mensaje.For example, the MessageBox API shown in this walkthrough accepts an integer argument called Typ that controls how the message box is displayed. Puede determinar el valor numérico de estas constantes mediante el examen de las #define instrucciones del archivo WinUser. h.You can determine the numeric value of these constants by examining the #define statements in the file WinUser.h. Los valores numéricos se suelen mostrar en formato hexadecimal, por lo que es posible que desee usar una calculadora para agregarlos y convertirlos a decimal.The numeric values are generally shown in hexadecimal, so you may want to use a calculator to add them and convert to decimal. Por ejemplo, si desea combinar las constantes del estilo de exclamación MB_ICONEXCLAMATION 0x00000030 y el estilo MB_YESNO yes/no 0x00000004, puede Agregar los números y obtener un resultado de 0x00000034 o 52 decimal.For example, if you want to combine the constants for the exclamation style MB_ICONEXCLAMATION 0x00000030 and the Yes/No style MB_YESNO 0x00000004, you can add the numbers and get a result of 0x00000034, or 52 decimal. Aunque puede usar el resultado decimal directamente, es mejor declarar estos valores como constantes en la aplicación y combinarlos mediante el Or operador.Although you can use the decimal result directly, it is better to declare these values as constants in your application and combine them using the Or operator.

Para declarar constantes para las llamadas a la API de WindowsTo declare constants for Windows API calls
  1. Consulte la documentación de la función de Windows a la que está llamando.Consult the documentation for the Windows function you are calling. Determine el nombre de las constantes que utiliza y el nombre del archivo. h que contiene los valores numéricos de estas constantes.Determine the name of the constants it uses and the name of the .h file that contains the numeric values for these constants.

  2. Use un editor de texto, como el Bloc de notas, para ver el contenido del archivo de encabezado (. h) y buscar los valores asociados a las constantes que está usando.Use a text editor, such as Notepad, to view the contents of the header (.h) file, and find the values associated with the constants you are using. Por ejemplo, la MessageBox API usa la constante MB_ICONQUESTION para mostrar un signo de interrogación en el cuadro de mensaje.For example, the MessageBox API uses the constant MB_ICONQUESTION to show a question mark in the message box. La definición de MB_ICONQUESTION está en WinUser. h y aparece de la siguiente manera:The definition for MB_ICONQUESTION is in WinUser.h and appears as follows:

    #define MB_ICONQUESTION 0x00000020L

  3. Agregue instrucciones Const equivalentes a la clase o módulo para que estas constantes estén disponibles para la aplicación.Add equivalent Const statements to your class or module to make these constants available to your application. Por ejemplo:For example:

    Const MB_ICONQUESTION As Integer = &H20
    Const MB_YESNO As Integer = &H4
    Const IDYES As Integer = 6
    Const IDNO As Integer = 7
    
Para llamar al procedimiento DLLTo call the DLL procedure
  1. Agregue un botón denominado Button1 al formulario de inicio para el proyecto y, a continuación, haga doble clic en él para ver su código.Add a button named Button1 to the startup form for your project, and then double-click it to view its code. Se muestra el controlador de eventos para el botón.The event handler for the button is displayed.

  2. Agregue código al Click controlador de eventos para el botón que agregó, para llamar al procedimiento y proporcione los argumentos adecuados:Add code to the Click event handler for the button you added, to call the procedure and provide the appropriate arguments:

    Private Sub Button1_Click(ByVal sender As System.Object,
        ByVal e As System.EventArgs) Handles Button1.Click
    
        ' Stores the return value.
        Dim RetVal As Integer
        RetVal = MBox(0, "Declare DLL Test", "Windows API MessageBox",
            MB_ICONQUESTION Or MB_YESNO)
    
        ' Check the return value.
        If RetVal = IDYES Then
            MsgBox("You chose Yes")
        Else
            MsgBox("You chose No")
        End If
    End Sub
    
  3. Ejecute el proyecto presionando F5.Run the project by pressing F5. El cuadro de mensaje se muestra con los botones y sin respuesta.The message box is displayed with both Yes and No response buttons. Haga clic en cualquiera de ellas.Click either one.

Serialización de datosData Marshaling

Visual Basic convierte automáticamente los tipos de datos de los parámetros y los valores devueltos para las llamadas a la API MarshalAs de Windows, pero puede usar el atributo para especificar explícitamente los tipos de datos no administrados que una API espera.Visual Basic automatically converts the data types of parameters and return values for Windows API calls, but you can use the MarshalAs attribute to explicitly specify unmanaged data types that an API expects. Para obtener más información sobre el cálculo de referencias de interoperabilidad, vea serialización de interoperabilidad.For more information about interop marshaling, see Interop Marshaling.

Para usar declare y MarshalAs en una llamada APITo use Declare and MarshalAs in an API call
  1. Determine el nombre de la función a la que desea llamar, además de sus argumentos, tipos de datos y valor devuelto.Determine the name of the function you want to call, plus its arguments, data types, and return value.

  2. Para simplificar el acceso MarshalAs al atributo, agregue Imports una instrucción a la parte superior del código de la clase o módulo, como en el ejemplo siguiente:To simplify access to the MarshalAs attribute, add an Imports statement to the top of the code for the class or module, as in the following example:

    Imports System.Runtime.InteropServices
    
  3. Agregue un prototipo de función para la función importada a la clase o módulo que está usando y aplique MarshalAs el atributo a los parámetros o el valor devuelto.Add a function prototype for the imported function to the class or module you are using, and apply the MarshalAs attribute to the parameters or return value. En el ejemplo siguiente, se calculan las referencias void* AsAnyde una llamada API que espera que el tipo sea:In the following example, an API call that expects the type void* is marshaled as AsAny:

    Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" (
        ByVal x As Short,
        <MarshalAsAttribute(UnmanagedType.AsAny)>
            ByVal o As Object)
    

Llamadas API con DllImportAPI Calls Using DllImport

El DllImport atributo proporciona una segunda manera de llamar a funciones en archivos dll sin bibliotecas de tipos.The DllImport attribute provides a second way to call functions in DLLs without type libraries. DllImportes aproximadamente equivalente a utilizar una Declare instrucción pero proporciona más control sobre cómo se llama a las funciones.DllImport is roughly equivalent to using a Declare statement but provides more control over how functions are called.

Puede usar DllImport con la mayoría de las llamadas a la API de Windows siempre y cuando la llamada haga referencia a un método compartido (a veces denominado static).You can use DllImport with most Windows API calls as long as the call refers to a shared (sometimes called static) method. No se pueden usar métodos que requieran una instancia de una clase.You cannot use methods that require an instance of a class. A diferencia Declare de las DllImport instrucciones, las llamadas MarshalAs no pueden usar el atributo.Unlike Declare statements, DllImport calls cannot use the MarshalAs attribute.

Para llamar a una API de Windows mediante el atributo DllImportTo call a Windows API using the DllImport attribute

  1. Abra un nuevo proyecto de aplicación para Windows; para ello, haga clic en nuevo en el menú archivo y, a continuación, haga clic en proyecto.Open a new Windows Application project by clicking New on the File menu, and then clicking Project. Aparecerá el cuadro de diálogo Nuevo proyecto .The New Project dialog box appears.

  2. Seleccione aplicación de Windows en la lista de plantillas de proyecto de Visual Basic.Select Windows Application from the list of Visual Basic project templates. Se muestra el nuevo proyecto.The new project is displayed.

  3. Agregue un botón denominado Button2 al formulario de inicio.Add a button named Button2 to the startup form.

  4. Haga doble clic Button2 para abrir la vista de código del formulario.Double-click Button2 to open the code view for the form.

  5. Para simplificar el DllImportacceso a, Imports agregue una instrucción a la parte superior del código para la clase de formulario de Inicio:To simplify access to DllImport, add an Imports statement to the top of the code for the startup form class:

    Imports System.Runtime.InteropServices
    
  6. Declare una función vacía antes End Class de la instrucción del formulario y asigne un nombre MoveFilea la función.Declare an empty function preceding the End Class statement for the form, and name the function MoveFile.

  7. Aplique los Public modificadores y Shared a la declaración de función y establezca los MoveFile parámetros para en función de los argumentos que usa la función de la API de Windows:Apply the Public and Shared modifiers to the function declaration and set parameters for MoveFile based on the arguments the Windows API function uses:

    Public Shared Function MoveFile(
        ByVal src As String,
        ByVal dst As String) As Boolean
        ' Leave the body of the function empty.
    End Function
    

    La función puede tener cualquier nombre de procedimiento válido; el DllImport atributo especifica el nombre del archivo dll.Your function can have any valid procedure name; the DllImport attribute specifies the name in the DLL. También controla el cálculo de referencias de interoperabilidad para los parámetros y los valores devueltos, por lo que puede elegir los tipos de datos de Visual Studio que son similares a los tipos de datos que usa la API.It also handles interoperability marshaling for the parameters and return values, so you can choose Visual Studio data types that are similar to the data types the API uses.

  8. Aplique el DllImport atributo a la función vacía.Apply the DllImport attribute to the empty function. El primer parámetro es el nombre y la ubicación del archivo DLL que contiene la función a la que se está llamando.The first parameter is the name and location of the DLL containing the function you are calling. No es necesario especificar la ruta de acceso de los archivos que se encuentran en los directorios del sistema de Windows.You do not need to specify the path for files located in the Windows system directories. El segundo parámetro es un argumento con nombre que especifica el nombre de la función en la API de Windows.The second parameter is a named argument that specifies the name of the function in the Windows API. En este ejemplo, el DllImport atributo obliga a que MoveFile se reenvíen MoveFileW las llamadas a en Kernel32. DLL.In this example, the DllImport attribute forces calls to MoveFile to be forwarded to MoveFileW in KERNEL32.DLL. El MoveFileW método copia un archivo de la ruta src de acceso a dstla ruta de acceso.The MoveFileW method copies a file from the path src to the path dst.

    <DllImport("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
        ' Leave the body of the function empty.
    End Function
    
  9. Agregue código al Button2_Click controlador de eventos para llamar a la función:Add code to the Button2_Click event handler to call the function:

    Private Sub Button2_Click(ByVal sender As System.Object,
        ByVal e As System.EventArgs) Handles Button2.Click
    
        Dim RetVal As Boolean = MoveFile("c:\tmp\Test.txt", "c:\Test.txt")
        If RetVal = True Then
            MsgBox("The file was moved successfully.")
        Else
            MsgBox("The file could not be moved.")
        End If
    End Sub
    
  10. Cree un archivo denominado test. txt y colóquelo en el directorio C:\Tmp del disco duro.Create a file named Test.txt and place it in the C:\Tmp directory on your hard drive. Cree el directorio tmp si es necesario.Create the Tmp directory if necessary.

  11. Presione F5 para iniciar la aplicación.Press F5 to start the application. Aparece el formulario principal.The main form appears.

  12. Haga clic en BUTTON2.Click Button2. Se muestra el mensaje "el archivo se ha despasado correctamente" si se puede cambiar el archivo.The message "The file was moved successfully" is displayed if the file can be moved.

Vea tambiénSee also