Declare Statement

Dichiara un riferimento a una routine implementata in un file esterno.

Sintassi

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

Parti

Osservazioni:

In alcuni casi è necessario chiamare una routine definita in un file ,ad esempio una DLL o una risorsa di codice, all'esterno del progetto. In questo caso, il compilatore Visual Basic non ha accesso alle informazioni necessarie per chiamare correttamente la routine, ad esempio dove si trova la routine, come viene identificata, la sequenza chiamante e il tipo restituito e il set di caratteri stringa utilizzato. L'istruzione Declare crea un riferimento a una routine esterna e fornisce queste informazioni necessarie.

È possibile usare Declare solo a livello di modulo. Ciò significa che il contesto di dichiarazione per un riferimento esterno deve essere una classe, una struttura o un modulo e non può essere un file di origine, uno spazio dei nomi, un'interfaccia, una routine o un blocco. Per altre informazioni, vedere Contesti di dichiarazione e livelli di accesso predefiniti.

Per impostazione predefinita, i riferimenti esterni sono Accesso pubblico . È possibile regolare i livelli di accesso con i modificatori di accesso.

Regole

• Attributi. È possibile applicare attributi a un riferimento esterno. Qualsiasi attributo applicato ha effetto solo nel progetto, non nel file esterno.

• Modificatori. Le procedure esterne sono condivise in modo implicito. Non è possibile usare la Shared parola chiave quando si dichiara un riferimento esterno e non è possibile modificarne lo stato condiviso.

  Una procedura esterna non può partecipare all'override, implementare i membri dell'interfaccia o gestire gli eventi. Di conseguenza, non è possibile usare la Overridesparola chiave , NotOverridableOverridable, MustOverride, Implements, o Handles in un'istruzione Declare .

• Nome procedura esterna. Non è necessario assegnare a questo riferimento esterno lo stesso nome (in name) del nome del punto di ingresso della routine all'interno del file esterno (aliasname). È possibile usare una Alias clausola per specificare il nome del punto di ingresso. Ciò può essere utile se la routine esterna ha lo stesso nome di un modificatore riservato di Visual Basic o di una variabile, di una routine o di qualsiasi altro elemento di programmazione nello stesso ambito.

  Annotazioni

  I nomi dei punti di ingresso nella maggior parte delle DLL fanno distinzione tra maiuscole e minuscole.

• Numero procedura esterna. In alternativa, è possibile utilizzare una Alias clausola per specificare il numero ordinale del punto di ingresso all'interno della tabella di esportazione del file esterno. A tale scopo, iniziare aliasname con un segno di numero (#). Ciò può essere utile se un carattere nel nome della routine esterna non è consentito in Visual Basic o se il file esterno esporta la routine senza un nome.

Regole del tipo di dati

• Tipi di dati dei parametri. Se Option Strict è On, è necessario specificare il tipo di dati di ogni parametro in parameterlist. Può trattarsi di qualsiasi tipo di dati o nome di un'enumerazione, struttura, classe o interfaccia. All'interno parameterlistdi si usa una As clausola per specificare il tipo di dati dell'argomento da passare a ogni parametro.

  Annotazioni

  Se la procedura esterna non è stata scritta per .NET Framework, è necessario prestare attenzione alla corrispondenza dei tipi di dati. Ad esempio, se si dichiara un riferimento esterno a una routine di Visual Basic 6.0 con un Integer parametro (16 bit in Visual Basic 6.0), è necessario identificare l'argomento corrispondente come Short nell'istruzione Declare , perché questo è il tipo integer a 16 bit in Visual Basic. Analogamente, Long ha una larghezza dei dati diversa in Visual Basic 6.0 e Date viene implementata in modo diverso.

• Tipo di dati restituito. Se la routine esterna è e FunctionOption Strict è On, è necessario specificare il tipo di dati del valore restituito al codice chiamante. Può trattarsi di qualsiasi tipo di dati o nome di un'enumerazione, struttura, classe o interfaccia.

  Annotazioni

  Il compilatore Visual Basic non verifica che i tipi di dati siano compatibili con quelli della procedura esterna. In caso di mancata corrispondenza, Common Language Runtime genera un'eccezione MarshalDirectiveException in fase di esecuzione.

• Tipi di dati predefiniti. Se Option Strict è Off e non si specifica il tipo di dati di un parametro in parameterlist, il compilatore di Visual Basic converte l'argomento corrispondente nel tipo di dati Object. Analogamente, se non si specifica returntype, il compilatore accetta il tipo di dati restituito come Object.

  Annotazioni

  Poiché si sta gestendo una procedura esterna che potrebbe essere stata scritta in una piattaforma diversa, è pericoloso fare ipotesi sui tipi di dati o consentire loro di impostare l'impostazione predefinita. È molto più sicuro specificare il tipo di dati di ogni parametro e del valore restituito, se presente. Ciò migliora anche la leggibilità del codice.

Comportamento

• Ambito. Un riferimento esterno rientra nell'ambito in tutta la relativa classe, struttura o modulo.

• Durata della vita. Un riferimento esterno ha la stessa durata della classe, della struttura o del modulo in cui viene dichiarata.

• Chiamata di una routine esterna. Si chiama una routine esterna allo stesso modo in cui si chiama una Function routine o Sub , usandola in un'espressione se restituisce un valore o specificandola in un'istruzione call se non restituisce un valore.

  Si passano argomenti alla routine esterna esattamente come specificato da parameterlist nell'istruzione Declare . Non prendere in considerazione il modo in cui i parametri sono stati originariamente dichiarati nel file esterno. Analogamente, se è presente un valore restituito, usarlo esattamente come specificato da returntype nell'istruzione Declare .

• Set di caratteri. È possibile specificare in charsetmodifier che modo Visual Basic deve effettuare il marshalling delle stringhe quando chiama la routine esterna. Il Ansi modificatore indirizza Visual Basic al marshalling di tutte le stringhe ai valori ANSI e il Unicode modificatore lo indirizza al marshalling di tutte le stringhe ai valori Unicode. Il Auto modificatore indirizza Visual Basic al marshalling delle stringhe in base alle regole di .NET Framework in base al riferimento nameesterno o aliasname , se specificato. Il valore predefinito è Ansi.

  charsetmodifier specifica inoltre come Visual Basic deve cercare la routine esterna all'interno del relativo file esterno. Ansi e Unicode entrambi indirizzano Visual Basic a cercarlo senza modificarne il nome durante la ricerca. Auto indirizza Visual Basic a determinare il set di caratteri di base della piattaforma di runtime ed eventualmente modificare il nome della routine esterna, come indicato di seguito:

  • In una piattaforma Unicode, ad esempio Windows, cercare prima di tutto la procedura esterna senza alcuna modifica del nome. In caso di errore, aggiungere "W" alla fine del nome della procedura esterna e cercarlo di nuovo.

  • In una piattaforma ANSI cercare prima di tutto la procedura esterna senza alcuna modifica del nome. In caso di errore, aggiungere "A" alla fine del nome della routine esterna e cercarlo di nuovo.

• Meccanismo. Visual Basic usa il meccanismo PInvoke ( Platform Invoke ) di .NET Framework per risolvere e accedere a procedure esterne. L'istruzione Declare e la DllImportAttribute classe usano questo meccanismo automaticamente e non è necessaria alcuna conoscenza di PInvoke. Per altre informazioni, vedere Procedura dettagliata: Chiamata alle API di Windows.

Esempio 1

Nell'esempio seguente viene dichiarato un riferimento esterno a una Function routine che restituisce il nome utente corrente. Chiama quindi la procedura GetUserNameA esterna come parte della getUser procedura.

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

Esempio 2

fornisce DllImportAttribute un modo alternativo di usare le funzioni nel codice non gestito. Nell'esempio seguente viene dichiarata una funzione importata senza usare un'istruzione 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

Vedere anche

• LastDllError
• Dichiarazione Imports (.NET Namespace e Tipo)
• Operatore AddressOf
• Dichiarazione di Funzione
• Dichiarazione Sub
• Elenco parametri
• Istruzione Call
• Procedura dettagliata: Chiamata di API Windows