Instrução Declare

Artigo
08/08/2011

Declara uma referência a um procedimento implementado em um arquivo externo.

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

Parts

Term	Definition
attributelist	Optional. See Attribute List.
accessmodifier	Optional. Can be one of the following: Public Protected Friend Private Protected Friend See Níveis de acesso em Visual Basic.
Shadows	Optional. See Shadows.
charsetmodifier	Optional. Especifica o conjunto de caracteres e o arquivo de informações de pesquisa. Can be one of the following: Ansi (Visual Basic) (default) Unicode (Visual Basic) Auto (Visual Basic)
Sub	Opcional, mas um Sub ou Function deve aparecer. Indica que o procedimento externo não retornar um valor.
Function	Opcional, mas um Sub ou Function deve aparecer. Indica que o procedimento externo retorna um valor.
name	Required. ONome dessa referência externa. For more information, see Nomes de elementos declarados (Visual Basic).
Lib	Required. Apresenta um Lib cláusula, que identifica o arquivo externo (DLL ou código do recurso) que contém um procedimentode externo.
libname	Required. Nome do arquivo que contém o procedimentode declarado.
Alias	Optional. Indica que o procedimento que está sendo declarado não pode ser identificado em seu arquivo pelo nome especificado em name. Você especificar sua identificação no aliasname.
aliasname	Required if you use the Alias keyword. Seqüência de caracteres que identifica o procedimento de duas maneiras: O nome do ponto de entrada do procedimento dentro de seu arquivo, entre aspas ("") - ou - Um sinal numérico (#) seguido por um inteiro especificando o número ordinal de um ponto de entrada do procedimentoem seu arquivo
parameterlist	Necessário se o procedimento usa parâmetros. See Lista de parâmetros (Visual Basic).
returntype	Necessário se Function for especificado e Option Strict é On. Tipo de dados do valor retornado pelo procedimento.

Comentários

Às vezes você precisa chamar um procedimento definido em um arquivo (como uma DLL ou código do recurso) fora do seu projeto. Quando você fizer isso, o compilador Visual Basic não tem acesso às informações necessárias para chamar o procedimento corretamente, como, por exemplo, onde se encontra o procedimento , como é identificado, sua sequência de chamada e tipo de retorno e de seqüência de caracteres conjunto de caracteres que ele usa. O Declarededemonstrativo cria uma referência a um procedimento de externo e fornece essas informações necessárias.

Você pode usar Declare somente no nível de módulo . Isso significa que o dedeclaraçãocontexto para uma referência externa deve ser uma classe, estruturaou móduloe não pode ser o arquivo de fonte , namespace, interface, procedimentoou bloco. For more information, see Contextos de declaração e níveis de acesso padrão (Visual Basic).

ReferênciasExterno padrão Público (Visual Basic) de acesso. You can adjust their access levels with the access modifiers.

Rules

Atributos. Você pode aplicar atributos para uma referência externa. Qualquer atributo aplicar tem efeito somente no seu projeto, e não no arquivo externo.
Modificadores. ProcedimentosExterno são implicitamente Compartilhamento (Visual Basic). Não é possível usar o Shared palavra-chave ao declarar uma referência externa e você não pode alterar seu statusde compartilhado.

Um procedimento de externo não é possível participar substituindo, implementar membros de interface ou manipular eventos. Da mesma forma, você não pode usar o Overrides, Overridable, NotOverridable, MustOverride, Implements, ou Handlesapalavra-chave em um Declaredemonstrativo.
Externo Nomedo procedimento. Não é necessário dar esta referência externa o mesmo nome (em name) como o procedimentoda entrada-nome do ponto em seu arquivo externo (aliasname). Você pode usar um Alias cláusula para especificar a entrada-nome do ponto. Isso pode ser útil se o procedimento externo tem o mesmo nome como um modificador de Visual Basic reservado ou uma variável, procedimentoou qualquer outro elemento de programação no mesmo escopo.

Observação

Nomes de ponto de entrada-na maioria das DLLs são confidencial caso-.
Externo Númerodo procedimento. Como alternativa, você pode usar um Alias ponto cláusula para especificar o número ordinal da entrada da tabela de exportar do arquivo externo. Para fazer isso, começar a aliasname com um sinal numérico (#). Isso pode ser útil se qualquer caractere no nome do procedimento de externo não é permitido em Visual Basic, ou se o arquivo externo exporta o procedimento sem um nome.

Observação
Nomes de ponto de entrada-na maioria das DLLs são confidencial caso-.

Data Type Rules

Tipos de dados de parâmetro. Se Option Strict é On, você deve especificar o tipo de dados de cada parâmetro na parameterlist. Isso pode ser qualquer tipo de dados ou o nome de uma enumeração, estrutura, classeou interface. Dentro de parameterlist, você pode usar um As cláusula para especificar o tipo de dados do argumento a ser passada para cada parâmetro.

Observação
Se o procedimento externo não foi escrito para o.NET Framework, você deve observar que os tipos de dados correspondem. Por exemplo, se você declarar uma referência externa para um procedimento do Visual Basic 6.0 com um Integerparâmetro (16 bits no Visual Basic 6.0), você deve identificar o argumento correspondente como Short na Declarededemonstrativo, porque esse é o tipo inteiro de bit-16 no Visual Basic. Da mesma forma, Long tem uma largura de dados diferentes no Visual Basic 6.0, e Date é implementado de maneira diferente.

Se o procedimento externo não foi escrito para o.NET Framework, você deve observar que os tipos de dados correspondem. Por exemplo, se você declarar uma referência externa para um procedimento do Visual Basic 6.0 com um Integerparâmetro (16 bits no Visual Basic 6.0), você deve identificar o argumento correspondente como Short na Declarededemonstrativo, porque esse é o tipo inteiro de bit-16 no Visual Basic. Da mesma forma, Long tem uma largura de dados diferentes no Visual Basic 6.0, e Date é implementado de maneira diferente.

Retorne o Tipode dados. Se o procedimento externo é um Function e Option Strict é On, você deve especificar o tipo de dados do valor retornado para o código de chamada. Isso pode ser qualquer tipo de dados ou o nome de uma enumeração, estrutura, classeou interface.

Observação
O compilador Visual Basic verifica se os tipos de dados são compatíveis com aqueles do procedimentoexterno. Se houver uma incompatibilidade, o Common Language Runtime gera um MarshalDirectiveExceptiondeexceção em tempo de execução.

Padrão Tipos de dados. Se Option Strict é Off e você não especificar o tipo de dados de um parâmetro no parameterlist, o compilador Visual Basic converte o argumento correspondente para o Tipo de dados Object. Da mesma forma, se você não especificar returntype, o compilador usa o tipo de dados de retorno a ser Object.

Observação
Porque você está lidando com um procedimento externo que talvez tenha sido escrito em outra plataforma, é perigoso para fazer suposições sobre os tipos de dados ou para permitir o padrão. É muito mais seguro especificar o tipo de dados de cada parâmetro e o valor retornado, se houver. Isso também melhora a legibilidade do código.

Behavior

Escopo. Uma referência externa está no escopo em toda a sua classe, estruturaou módulo.
O tempo de vida. Uma referência externa tem o mesmo tempo de vida como a classe, estruturaou módulo no qual é declarada.
Chamando um procedimento Externo . Você chamar um procedimento de externo, da mesma maneira que você chamar um Function ou Sub procedimento— usando-o em uma expressão se ele retorna um valor, ou especificando-o em um Instrução Call (Visual Basic) se não retornar um valor.

Você passar argumentos para o procedimento externo exatamente conforme especificado pelo parameterlist na Declare demonstrativo. Não leve em consideração como os parâmetros originalmente foram declarados no arquivo externo. Da mesma forma, se houver um valor retornado, usá-lo exatamente como especificado pelo returntype na Declare demonstrativo.
Conjuntos de caracteres. Você pode especificar em charsetmodifier como Visual Basic deve realizar marshaling strings quando ele chama o procedimentoexterno. O Ansi Visual Basic direciona modificador para realizar marshaling todas as seqüências de caracteres em valores ANSI e o Unicode modificador direciona para realizar marshaling todas as seqüências de caracteres para todos os valores Unicode . O Auto modificador direciona o Visual Basic para realizar marshaling seqüências de acordo com.Regras do NET Framework baseiam a referência externa name, ou aliasname se especificado. O valor padrão é Ansi.

charsetmodifiertambém especifica a aparência de Visual Basic até o procedimento externo em seu arquivo externo. Ansie Unicode tanto direta de Visual Basic procurá-lo sem modificar seu nome durante a pesquisa. Autodireciona o Visual Basic para determinar a base de conjunto de caracteres da execução de- plataforma de tempo e possivelmente modificar o nome do procedimento de externo, da seguinte maneira:
- Em uma ANSI plataforma, como, por exemplo, Windows 95, Windows 98 ou Windows Millennium Edition, primeiro procure o procedimento externo com nenhuma modificação do nome. Se isso falhar, acrescentar "A" ao final do procedimento externo nome e procurá-lo novamente.
- Em uma Unicode plataforma, como, por exemplo, Windows NT, o Windows 2000 ou Windows XP, procure pela primeira vez o procedimento externo com nenhuma modificação do nome. Se isso falhar, acrescentar "W" ao final do procedimento externo nome e procurá-lo novamente.
Mechanism. Visual Basic usa o.NET Frameworkde invocação deplataforma (PInvoke) o mecanismo para resolver e acesso procedimentos externos. O Declare demonstrativo e a DllImportAttribute classe ambas usar esse mecanismo automaticamente e não é necessário qualquer conhecimento de PInvoke. For more information, see Passo a passo: Chamando APIs do Windows (Visual Basic).

Observação sobre segurança
Se o procedimento externo é executado fora Common Language Runtime (CLR), é código não gerenciado. Quando você chamar tal um procedimento, por exemplo, uma função de API do Win32 ou ummétododo COM, você poderá expor seu aplicativo a riscos de segurança . For more information, see Código não gerenciado.

Exemplo

O exemplo a seguir declara uma referência externa para um Function procedimento retorna o nome do usuário atual. Em seguida, chama o procedimentoexternoGetUserNameA como parte do getUserprocedimento.

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

O DllImportAttribute fornece uma maneira alternativa de utilização de funções no código não gerenciado. O exemplo a seguir declara uma função de importados sem usar um Declare demonstrativo.

' 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