Procedura dettagliata: Chiamata di API Windows (Visual Basic)Walkthrough: Calling Windows APIs (Visual Basic)

Le API di Windows sono librerie a collegamento dinamico (dll) che fanno parte del sistema operativo Windows.Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows operating system. Vengono usati per eseguire attività quando è difficile scrivere procedure equivalenti personalizzate.You use them to perform tasks when it is difficult to write equivalent procedures of your own. Windows, ad esempio, fornisce una funzione FlashWindowEx denominata che consente di fare in modo che la barra del titolo di un'applicazione venga alternata tra le tonalità chiaro e scuro.For example, Windows provides a function named FlashWindowEx that lets you make the title bar for an application alternate between light and dark shades.

Il vantaggio di usare le API di Windows nel codice è che consentono di risparmiare tempo di sviluppo perché contengono dozzine di funzioni utili già scritte e in attesa di essere usate.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. Lo svantaggio è che le API di Windows possono essere difficili da utilizzare e non perdonare quando si verificano problemi.The disadvantage is that Windows APIs can be difficult to work with and unforgiving when things go wrong.

Le API di Windows rappresentano una categoria speciale di interoperabilità.Windows APIs represent a special category of interoperability. Le API Windows non utilizzano codice gestito, non dispongono di librerie dei tipi predefinite e utilizzano tipi di dati diversi da quelli utilizzati 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. A causa di queste differenze, e poiché le API di Windows non sono oggetti COM, l'interoperabilità con le API Windows e la .NET Framework viene eseguita utilizzando platform invoke 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. Platform Invoke è un servizio che consente al codice gestito di chiamare funzioni non gestite implementate in dll.Platform invoke is a service that enables managed code to call unmanaged functions implemented in DLLs. Per ulteriori informazioni, vedere utilizzo di funzioni dll non gestite.For more information, see Consuming Unmanaged DLL Functions. È possibile utilizzare PInvoke in Visual Basic utilizzando l' Declare istruzione o applicando l' DllImport attributo a una routine vuota.You can use PInvoke in Visual Basic by using either the Declare statement or applying the DllImport attribute to an empty procedure.

Le chiamate all'API di Windows rappresentano una parte importante della programmazione Visual Basic in passato, ma sono raramente necessarie 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. Quando possibile, è consigliabile usare codice gestito dal .NET Framework per eseguire attività, anziché chiamate API Windows.Whenever possible, you should use managed code from the .NET Framework to perform tasks, instead of Windows API calls. In questa procedura dettagliata vengono fornite informazioni sulle situazioni in cui è necessario utilizzare le API di Windows.This walkthrough provides information for those situations in which using Windows APIs is necessary.

Nota

Nomi o percorsi visualizzati per alcuni elementi dell'interfaccia utente di Visual Studio nelle istruzioni seguenti potrebbero essere diversi nel computer in uso.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. La versione di Visual Studio in uso e le impostazioni configurate determinano questi elementi.The Visual Studio edition that you have and the settings that you use determine these elements. Per altre informazioni, vedere Personalizzazione dell'IDE.For more information, see Personalizing the IDE.

Chiamate API con DECLAREAPI Calls Using Declare

Il modo più comune per chiamare le API Windows consiste nell'utilizzare Declare l'istruzione.The most common way to call Windows APIs is by using the Declare statement.

Per dichiarare una procedura DLLTo declare a DLL procedure

  1. Determinare il nome della funzione che si desidera chiamare, più gli argomenti, i tipi di argomento e il valore restituito, nonché il nome e il percorso della DLL che 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

    Per informazioni complete sulle API Windows, vedere la documentazione di Win32 SDK nell'API Windows di Platform SDK.For complete information about the Windows APIs, see the Win32 SDK documentation in the Platform SDK Windows API. Per ulteriori informazioni sulle costanti utilizzate dalle API di Windows, esaminare i file di intestazione come Windows. h inclusi in Platform SDK.For more information about the constants that Windows APIs use, examine the header files such as Windows.h included with the Platform SDK.

  2. Aprire un nuovo progetto di applicazione Windows scegliendo nuovo dal menu file , quindi fare clic su progetto.Open a new Windows Application project by clicking New on the File menu, and then clicking Project. Verrà visualizzata la finestra di dialogo Nuovo progetto .The New Project dialog box appears.

  3. Selezionare applicazione Windows dall'elenco dei modelli di progetto Visual Basic.Select Windows Application from the list of Visual Basic project templates. Verrà visualizzato il nuovo progetto.The new project is displayed.

  4. Aggiungere la funzione Declare seguente alla classe o al modulo in cui si vuole usare la 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
    

Parti dell'istruzione DeclareParts of the Declare Statement

L' Declare istruzione include gli elementi seguenti.The Declare statement includes the following elements.

Modificatore automaticoAuto modifier

Il Auto modificatore indica al runtime di convertire la stringa in base al nome del metodo in base alle regole Common Language Runtime (o al nome alias, se specificato).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).

Parole chiave lib e aliasLib and Alias keywords

Il nome che segue Function la parola chiave è il nome usato dal programma per accedere alla funzione importata.The name following the Function keyword is the name your program uses to access the imported function. Può corrispondere al nome reale della funzione che si sta chiamando oppure è possibile utilizzare qualsiasi nome di routine valido e quindi utilizzare la Alias parola chiave per specificare il nome reale della funzione che si sta chiamando.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.

Specificare la Lib parola chiave, seguita dal nome e dal percorso della dll che contiene la funzione che si sta chiamando.Specify the Lib keyword, followed by the name and location of the DLL that contains the function you are calling. Non è necessario specificare il percorso per i file presenti nelle directory di sistema di Windows.You do not need to specify the path for files located in the Windows system directories.

Usare la Alias parola chiave se il nome della funzione che si sta chiamando non è un nome di stored procedure Visual Basic valido o è in conflitto con il nome di altri elementi nell'applicazione.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 il nome true della funzione chiamata.Alias indicates the true name of the function being called.

Dichiarazioni di argomenti e tipi di datiArgument and Data Type Declarations

Dichiarare gli argomenti e i relativi tipi di dati.Declare the arguments and their data types. Questa parte può essere complessa perché i tipi di dati usati da Windows non corrispondono ai tipi di dati di Visual Studio.This part can be challenging because the data types that Windows uses do not correspond to Visual Studio data types. Visual Basic esegue una grande parte del lavoro convertendo gli argomenti in tipi di dati compatibili, un processo denominato marshalling.Visual Basic does a lot of the work for you by converting arguments to compatible data types, a process called marshaling. È possibile controllare System.Runtime.InteropServices in modo esplicito il modo in cui viene eseguito MarshalAsAttribute il marshalling degli argomenti utilizzando l'attributo definito nello spazio dei nomi.You can explicitly control how arguments are marshaled by using the MarshalAsAttribute attribute defined in the System.Runtime.InteropServices namespace.

Nota

Le versioni precedenti di Visual Basic consentivano di As Anydichiarare parametri, vale a dire che potevano essere utilizzati dati di qualsiasi tipo di dati.Previous versions of Visual Basic allowed you to declare parameters As Any, meaning that data of any data type could be used. Visual Basic richiede l'utilizzo di un tipo di dati specifico per Declare tutte le istruzioni.Visual Basic requires that you use a specific data type for all Declare statements.

Costanti API WindowsWindows API Constants

Alcuni argomenti sono combinazioni di costanti.Some arguments are combinations of constants. Ad esempio, l' MessageBox API mostrata in questa procedura dettagliata accetta un argomento Typ Integer denominato che controlla la modalità di visualizzazione della finestra di messaggio.For example, the MessageBox API shown in this walkthrough accepts an integer argument called Typ that controls how the message box is displayed. È possibile determinare il valore numerico di queste costanti esaminando le #define istruzioni nel file WinUser. h.You can determine the numeric value of these constants by examining the #define statements in the file WinUser.h. I valori numerici sono in genere visualizzati in formato esadecimale, quindi è consigliabile usare un calcolatore per aggiungerli e convertirli in decimali.The numeric values are generally shown in hexadecimal, so you may want to use a calculator to add them and convert to decimal. Se, ad esempio, si desidera combinare le costanti per il punto esclamativo MB_ICONEXCLAMATION 0x00000030 e il 0x00000004 di stile MB_YESNO Yes/No, è possibile aggiungere i numeri e ottenere un risultato di 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. Sebbene sia possibile usare direttamente il risultato Decimal, è preferibile dichiarare questi valori come costanti nell'applicazione e combinarli usando l' Or operatore.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.

Per dichiarare costanti per le chiamate API WindowsTo declare constants for Windows API calls
  1. Consultare la documentazione per la funzione di Windows che si sta chiamando.Consult the documentation for the Windows function you are calling. Determinare il nome delle costanti utilizzate e il nome del file con estensione h che contiene i valori numerici per queste costanti.Determine the name of the constants it uses and the name of the .h file that contains the numeric values for these constants.

  2. Utilizzare un editor di testo, ad esempio Blocco note, per visualizzare il contenuto del file di intestazione (. h) e individuare i valori associati alle costanti utilizzate.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. Ad esempio, l' MessageBox API usa la costante MB_ICONQUESTION per visualizzare un punto interrogativo nella finestra di messaggio.For example, the MessageBox API uses the constant MB_ICONQUESTION to show a question mark in the message box. La definizione di MB_ICONQUESTION si trova in winuser. h e viene visualizzata come segue:The definition for MB_ICONQUESTION is in WinUser.h and appears as follows:

    #define MB_ICONQUESTION 0x00000020L

  3. Aggiungere istruzioni Const equivalenti alla classe o al modulo per rendere queste costanti disponibili per l'applicazione.Add equivalent Const statements to your class or module to make these constants available to your application. Ad esempio:For example:

    Const MB_ICONQUESTION As Integer = &H20
    Const MB_YESNO As Integer = &H4
    Const IDYES As Integer = 6
    Const IDNO As Integer = 7
    
Per chiamare la procedura DLLTo call the DLL procedure
  1. Aggiungere un pulsante denominato Button1 al modulo di avvio per il progetto, quindi fare doppio clic su di esso per visualizzarne il codice.Add a button named Button1 to the startup form for your project, and then double-click it to view its code. Viene visualizzato il gestore eventi per il pulsante.The event handler for the button is displayed.

  2. Aggiungere il codice al Click gestore eventi per il pulsante aggiunto, per chiamare la procedura e fornire gli argomenti appropriati: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. Eseguire il progetto premendo F5.Run the project by pressing F5. La finestra di messaggio viene visualizzata con i pulsanti e Nessuna risposta.The message box is displayed with both Yes and No response buttons. Fare clic su una delle due.Click either one.

Marshalling dei datiData Marshaling

Visual Basic converte automaticamente i tipi di dati dei parametri e i valori restituiti per le chiamate API Windows, ma è MarshalAs possibile usare l'attributo per specificare in modo esplicito i tipi di dati non gestiti previsti da un'API.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. Per ulteriori informazioni sul marshalling di interoperabilità, vedere marshallingdi interoperabilità.For more information about interop marshaling, see Interop Marshaling.

Per usare DECLARE e marshalling in una chiamata APITo use Declare and MarshalAs in an API call
  1. Determinare il nome della funzione che si desidera chiamare, più gli argomenti, i tipi di dati e il valore restituito.Determine the name of the function you want to call, plus its arguments, data types, and return value.

  2. Per semplificare l'accesso all' MarshalAs attributo, aggiungere un' Imports istruzione all'inizio del codice per la classe o il modulo, come nell'esempio seguente: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. Aggiungere un prototipo di funzione per la funzione importata alla classe o al modulo in uso e MarshalAs applicare l'attributo ai parametri o al valore restituito.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. Nell'esempio seguente viene effettuato il marshalling void* AsAnydi una chiamata API che prevede il tipo: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)
    

Chiamate API con DllImportAPI Calls Using DllImport

L' DllImport attributo fornisce un secondo modo per chiamare le funzioni nelle DLL senza librerie dei tipi.The DllImport attribute provides a second way to call functions in DLLs without type libraries. DllImportè approssimativamente equivalente all'uso di Declare un'istruzione, ma offre un maggiore controllo sulla modalità di chiamata delle funzioni.DllImport is roughly equivalent to using a Declare statement but provides more control over how functions are called.

È possibile utilizzare DllImport con la maggior parte delle chiamate API Windows purché la chiamata faccia riferimento a un metodo condiviso (talvolta chiamato statico).You can use DllImport with most Windows API calls as long as the call refers to a shared (sometimes called static) method. Non è possibile usare metodi che richiedono un'istanza di una classe.You cannot use methods that require an instance of a class. Diversamente Declare dalle istruzioni, DllImport le chiamate non possono MarshalAs utilizzare l'attributo.Unlike Declare statements, DllImport calls cannot use the MarshalAs attribute.

Per chiamare un'API Windows utilizzando l'attributo DllImportTo call a Windows API using the DllImport attribute

  1. Aprire un nuovo progetto di applicazione Windows scegliendo nuovo dal menu file , quindi fare clic su progetto.Open a new Windows Application project by clicking New on the File menu, and then clicking Project. Verrà visualizzata la finestra di dialogo Nuovo progetto .The New Project dialog box appears.

  2. Selezionare applicazione Windows dall'elenco dei modelli di progetto Visual Basic.Select Windows Application from the list of Visual Basic project templates. Verrà visualizzato il nuovo progetto.The new project is displayed.

  3. Aggiungere un pulsante denominato Button2 al modulo di avvio.Add a button named Button2 to the startup form.

  4. Fare doppio clic Button2 per aprire la visualizzazione codice per il form.Double-click Button2 to open the code view for the form.

  5. Per semplificare l'accesso DllImporta, aggiungere Imports un'istruzione all'inizio del codice per la classe del form di avvio: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. Dichiarare una funzione vuota che precede End Class l'istruzione per il form e assegnare un nome MoveFilealla funzione.Declare an empty function preceding the End Class statement for the form, and name the function MoveFile.

  7. Applicare i Public modificatori e Shared alla dichiarazione di funzione e impostare i parametri MoveFile per in base agli argomenti utilizzati dalla funzione API di 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 funzione può avere qualsiasi nome di routine valido; l' DllImport attributo specifica il nome nella dll.Your function can have any valid procedure name; the DllImport attribute specifies the name in the DLL. Gestisce anche il marshalling di interoperabilità per i parametri e i valori restituiti, quindi è possibile scegliere i tipi di dati di Visual Studio simili ai tipi di dati usati dall'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. Applicare l' DllImport attributo alla funzione vuota.Apply the DllImport attribute to the empty function. Il primo parametro è il nome e il percorso della DLL che contiene la funzione che si sta chiamando.The first parameter is the name and location of the DLL containing the function you are calling. Non è necessario specificare il percorso per i file presenti nelle directory di sistema di Windows.You do not need to specify the path for files located in the Windows system directories. Il secondo parametro è un argomento denominato che specifica il nome della funzione nell'API Windows.The second parameter is a named argument that specifies the name of the function in the Windows API. In questo esempio, l' DllImport attributo impone che le MoveFile chiamate a vengano trasmesse MoveFileW a in Kernel32. DLL.In this example, the DllImport attribute forces calls to MoveFile to be forwarded to MoveFileW in KERNEL32.DLL. Il MoveFileW metodo copia un file dal percorso src al percorso dst.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. Aggiungere il codice al Button2_Click gestore eventi per chiamare la funzione: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. Creare un file denominato test. txt e inserirlo nella directory C:\Tmp sul disco rigido.Create a file named Test.txt and place it in the C:\Tmp directory on your hard drive. Se necessario, creare la directory tmp.Create the Tmp directory if necessary.

  11. Premere F5 per avviare l’applicazione.Press F5 to start the application. Viene visualizzato il form principale.The main form appears.

  12. Fare clic su Button2.Click Button2. Il messaggio "il file è stato spostato correttamente" viene visualizzato se il file può essere spostato.The message "The file was moved successfully" is displayed if the file can be moved.

Vedere ancheSee also