Declare Statement

  • Articolo

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

Termine Definizione
attributelist Facoltativo. Vedere Elenco degli attributi.
accessmodifier Facoltativo. Può essere uno dei seguenti:

- Pubblica
- Protected
- Friend
- Privata
- Protected Friend
- Private Protected

Vedere Access levels in Visual Basic.
Shadows Facoltativo. Vedere Shadows.
charsetmodifier Facoltativo. Specifica le informazioni sul set di caratteri e sulla ricerca di file. Può essere uno dei seguenti:

- Ansi (impostazione predefinita)
- Unicode
- Auto
Sub Facoltativo, ma deve essere visualizzato Sub o Function. Indica che la routine esterna non restituisce un valore.
Function Facoltativo, ma deve essere visualizzato Sub o Function. Indica che la routine esterna restituisce un valore.
name Obbligatorio. Nome di questo riferimento esterno. Per altre informazioni, vedere Nomi di elementi dichiarati.
Lib Obbligatorio. Introduce una clausola Lib che identifica il file esterno (DLL o risorsa codice) contenente una routine esterna.
libname Obbligatorio. Nome del file che contiene la routine dichiarata.
Alias Facoltativo. Indica che la routine dichiarata non può essere identificata all'interno del relativo file dal nome specificato in name. L'utente specifica l'identificazione in aliasname.
aliasname Obbligatorio se si usa la parola chiave Alias. Stringa che identifica la routine in uno dei due modi seguenti:

Nome del punto di ingresso della routine all'interno del file, tra virgolette ("")

oppure

Simbolo di cancelletto (#) seguito da un numero intero che specifica il numero ordinale del punto di ingresso della routine all'interno del relativo file
parameterlist Obbligatorio se la routine accetta i parametri. Vedere Elenco parametri.
returntype Obbligatorio se si specifica Function e Option Strict è On. Tipo di dati del valore restituito dalla routine.

Osservazioni:

In alcuni casi è necessario chiamare una routine definita in un file, ad esempio una DLL o una risorsa del codice, all'esterno del progetto. In questo caso, il compilatore di 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.

Si può usare Declare solo a livello di modulo. In altri termini, il contesto della 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, una routine o un blocco. Per altre informazioni, vedere Contesti delle dichiarazioni e livelli di accesso predefiniti.

Per impostazione predefinita, l'accesso dei riferimenti esterni è Pubblico. È possibile regolare i livelli di accesso con i modificatori di accesso.

Regole

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

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

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

  • Nome della routine 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 clausola Alias 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.

    Nota

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

  • Numero della routine esterna. In alternativa, è possibile utilizzare una clausola Alias 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 simbolo di cancelletto (#). 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 è impostato su On, è necessario specificare il tipo di dati di ogni parametro in parameterlist. È possibile specificare qualsiasi tipo di dati o il nome di un'enumerazione, struttura, classe o interfaccia. All'interno di parameterlist si usa una clausola As per specificare il tipo di dati dell'argomento da passare a ogni parametro.

    Nota

    Se la routine 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 parametro Integer (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 restituiti. Se la routine esterna è Function e Option Strict è impostato su On, è necessario specificare il tipo di dati del valore restituito al codice chiamante. È possibile specificare qualsiasi tipo di dati o il nome di un'enumerazione, struttura, classe o interfaccia.

    Nota

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

  • Tipi di dati predefiniti. Se Option Strict è impostato su 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 che il tipo di dati restituito sia Object.

    Nota

    Poiché si sta gestendo una routine 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 per tutta la sua classe, struttura o modulo.

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

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

    Gli argomenti vengono passati 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 il modo in cui Visual Basic deve effettuare il marshalling delle stringhe quando chiama la routine esterna. Il modificatore Ansi indirizza Visual Basic al marshalling di tutte le stringhe ai valori ANSI e il modificatore Unicode lo indirizza al marshalling di tutte le stringhe ai valori Unicode. Il modificatore Auto indirizza Visual Basic al marshalling delle stringhe in base alle regole di .NET Framework basate 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 suo 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 routine esterna senza alcuna modifica del nome. Se la ricerca ha esito negativo, aggiungere "W" alla fine del nome della routine esterna e cercarlo di nuovo.

    • In una piattaforma ANSI cercare prima di tutto la routine esterna senza alcuna modifica del nome. Se la ricerca ha esito negativo, aggiungere "A" alla fine del nome della routine esterna e cercarlo di nuovo.

  • Meccanismo. Visual Basic usa il meccanismo platform invoke (PInvoke) di .NET Framework per risolvere e accedere a routine esterne. L'istruzione Declare e la classe DllImportAttribute usano entrambe questo meccanismo in modo automatico e non è necessaria alcuna conoscenza di PInvoke. Per altre informazioni, vedere Procedura dettagliata: chiamata delle API di Windows.

Importante

Se la routine esterna viene eseguita all'esterno di Common Language Runtime (CLR), si tratta di codice non gestito. Quando si chiama una routine di questo tipo, ad esempio una funzione delle API di Windows o un metodo COM, è possibile esporre l'applicazione a rischi per la sicurezza. Per altre informazioni, vedere Linee guida per la creazione di codice sicuro applicabili al codice non gestito.

Esempio 1

Nell'esempio seguente viene dichiarato un riferimento esterno a una routine Function che restituisce il nome utente corrente. Viene chiamata poi la routine esterna GetUserNameA come parte della routine 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

Esempio 2

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

Vedi anche