Instrução Declare

Artigo
05/09/2023

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

Sintaxe

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

Partes

Termo	Definição
`attributelist`	Opcional. Veja Lista de atributo.
`accessmodifier`	Opcional. Um dos seguintes pode ser feito: - Público - Protegido - Friend - Privado - Amigo Protegido - Particular Protegido Consulte Níveis de acesso no Visual Basic.
`Shadows`	Opcional. Confira Sombras.
`charsetmodifier`	Opcional. Especifica informações de conjunto de caracteres e pesquisa de arquivo. Um dos seguintes pode ser feito: - Ansi (padrão) - Unicode - Auto
`Sub`	Opcional, mas `Sub` ou `Function` deve aparecer. Indica que o procedimento externo não retorna um valor.
`Function`	Opcional, mas `Sub` ou `Function` deve aparecer. Indica que o procedimento externo retorna um valor.
`name`	Obrigatórios. Nome dessa referência externa. Para obter mais informações, consulte Nomes do Elemento Declarado.
`Lib`	Obrigatórios. Apresenta uma cláusula `Lib` que identifica o arquivo externo (DLL ou recurso de código) contendo um procedimento externo.
`libname`	Obrigatórios. Nome do arquivo que contém o procedimento declarado.
`Alias`	Opcional. Indica que o procedimento que está sendo declarado não pode ser identificado no arquivo pelo nome especificado em `name`. Especifique a identificação em `aliasname`.
`aliasname`	Obrigatório se você usar a palavra-chave `Alias`. Cadeia de caracteres que identifica o procedimento de duas maneiras: O nome do ponto de entrada do procedimento no arquivo, entre aspas (`""`) -ou- Um sinal numérico (`#`) seguido por um inteiro especificando o número ordinal do ponto de entrada do procedimento no arquivo
`parameterlist`	Necessário se o procedimento usa parâmetros. Consulte a Lista de parâmetros.
`returntype`	Obrigatório se `Function` for especificado e `Option Strict` for `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 um recurso de código) fora do projeto. Quando você faz isso, o compilador do Visual Basic não tem acesso às informações necessárias para chamar o procedimento corretamente, como onde o procedimento está localizado, como ele é identificado, sua sequência de chamada e tipo de retorno e o conjunto de caracteres de cadeia de caracteres usado. A instrução Declare cria uma referência a um procedimento externo e fornece essas informações necessárias.

Você só pode usar Declare no nível do módulo. Isso significa que o contexto de declaração de uma referência externa precisa ser uma classe, estrutura, módulo ou procedimento, e não pode ser um arquivo de origem, namespace, interface, procedimento ou bloco. Para obter mais informações, consulte Contextos de declaração e níveis de acesso padrão.

Referências externas padrão para acesso Público. Você pode ajustar os níveis de acesso com os modificadores de acesso.

Regras

Atributos. É possível aplicar atributos a uma referência externa. Qualquer atributo aplicado só tem efeito em seu projeto, não no arquivo externo.
Modificadores. Procedimentos externos são implicitamente Compartilhados. Não é possível usar a palavra-chave Shared ao declarar uma referência externa, nem alterar seu status compartilhado.

Um procedimento externo não pode participar da substituição, implementar membros da interface ou manipular eventos. Dessa forma, você não pode usar a Overrides, Overridable, NotOverridable, MustOverride, Implements ou Handles em uma instrução Declare.
Nome do procedimento externo. Você não precisa dar a essa referência externa o mesmo nome (em name) que o nome do ponto de entrada do procedimento em seu arquivo externo (aliasname). Você pode usar uma cláusula Alias para especificar o nome do ponto de entrada. Isso poderá ser útil se o procedimento externo tiver o mesmo nome que um modificador reservado do Visual Basic ou uma variável, procedimento ou outro elemento de programação no mesmo escopo.

Observação

Na maioria das DLLs, os nomes do ponto de entrada diferenciam maiúsculas de minúsculas.
Número do procedimento externo. Como alternativa, é possível usar uma cláusula Alias para especificar o número ordinal do ponto de entrada na tabela de exportação do arquivo externo. Para fazer isso, aliasname deve começar com uma tecla jogo da velha (#). Isso pode ser útil se qualquer caractere no nome do procedimento externo não for permitido no Visual Basic ou se o arquivo externo exportar o procedimento sem um nome.

Regras de tipo de dados

Tipos de dados do parâmetro. Se Option Strict for On, especifique o tipo de dados de cada parâmetro em parameterlist. Pode ser qualquer tipo de dados ou o nome de uma enumeração, estrutura, classe ou interface. Em parameterlist, use uma cláusula As para especificar o tipo de dados do argumento a ser passado para cada parâmetro.

Observação

Se o procedimento externo não foi gravado no .NET Framework, verifique se os tipos de dados correspondem. Por exemplo, se você declarar uma referência externa a um procedimento do Visual Basic 6.0 com um parâmetro Integer (16 bits no Visual Basic 6.0), identifique o argumento correspondente como Short na instrução Declare, pois esse é o tipo inteiro de 16 bits no Visual Basic. Da mesma forma, Long tem uma largura de dados diferente no Visual Basic 6.0 e Date é implementado de forma diferente.
Tipo de dados de retorno. Se o procedimento externo for Function e Option Strict for On, você deverá especificar o tipo de dados do valor retornado ao código de chamada. Pode ser qualquer tipo de dados ou o nome de uma enumeração, estrutura, classe ou interface.

Observação

O compilador do Visual Basic não verifica se os tipos de dados são compatíveis com os do procedimento externo. Se houver uma incompatibilidade, o Common Language Runtime gerará uma exceção MarshalDirectiveException no tempo de execução.
Tipos de dados padrão. Se Option Strict for Off e você não especificar o tipo de dados de um parâmetro em parameterlist, o compilador do Visual Basic converterá o argumento correspondente no Tipo de Dados do Objeto. Da mesma forma, se você não especificar returntype, o compilador usará o tipo de dados de retorno como Object.

Observação

Como você está lidando com um procedimento externo que pode ter sido gravado em uma plataforma diferente, é perigoso fazer qualquer suposição sobre tipos de dados ou permitir que eles sejam padrão. É mais seguro especificar o tipo de dados de cada parâmetro e do valor retornado, se houver. Isso também melhora a legibilidade do código.

Comportamento

Escopo. Uma referência externa está no escopo em toda a classe, estrutura ou módulo.
Tempo de vida. Uma referência externa tem o mesmo tempo de vida que a classe, a estrutura ou o módulo em que ela é declarada.
Chamada de um procedimento externo. Um procedimento externo é chamado da mesma forma que um procedimento Function ou Sub, usando-o em uma expressão se ele retorna um valor ou especificando-o em uma Instrução de Chamada se ele não retornar um valor.

Você passa argumentos para o procedimento externo exatamente conforme especificado por parameterlist na instrução Declare. Não considere como os parâmetros foram originalmente declarados no arquivo externo. Da mesma forma, se houver um valor retornado, use-o exatamente como especificado por returntypena instrução Declare.
Conjuntos de caracteres. Você pode especificar no charsetmodifier como o Visual Basic deve realizar marshal de cadeias de caracteres quando ele chama o procedimento externo. O modificador Ansi direciona o Visual Basic para realizar marshal de todas as cadeias de caracteres para valores ANSI e o modificador Unicode direciona-o para realizar marshal de todas as cadeias de caracteres para valores Unicode. O modificador Auto direciona o Visual Basic para realizar marshal de cadeias de caracteres de acordo com as regras do .NET Framework com base na referência externa name ou aliasname, se especificado. O valor padrão é Ansi.

charsetmodifier também especifica como o Visual Basic deve pesquisar o procedimento externo em seu arquivo externo. Ansi e Unicode direcionam o Visual Basic para pesquisá-lo sem modificar o nome durante a pesquisa. Auto direciona o Visual Basic para determinar o conjunto de caracteres base da plataforma do tempo de execução e, possivelmente, modificar o nome do procedimento externo, da seguinte maneira:
- Em uma plataforma Unicode, como o Windows, primeiro procure o procedimento externo sem modificação do nome. Se isso falhar, acrescente "W" ao final do nome do procedimento externo e procure-o novamente.
- Em uma plataforma ANSI, primeiro procure o procedimento externo sem modificação de nome. Se isso falhar, acrescente "A" ao final do nome do procedimento externo e procure-o novamente.
Mecanismo. O Visual Basic usa o mecanismo de invocação de plataforma (PInvoke) do .NET Framework para resolver e acessar procedimentos externos. A instrução Declare e a classe DllImportAttribute usam esse mecanismo automaticamente e você não precisa ter conhecimento do PInvoke. Para obter mais informações, consulte Passo a passo: Fazer chamadas de APIs do Windows.

Importante

Se o procedimento externo for executado fora do CLR (Common Language Runtime), ele será um código não gerenciado. Ao chamar esse procedimento, por exemplo, uma função de API do Windows ou um método COM, seu aplicativo pode ficar exposto a riscos de segurança. Para obter mais informações, consulte Diretrizes de codificação segura para código não gerenciado.

Exemplo 1

O exemplo a seguir declara uma referência externa a um procedimento Function que retorna o nome de usuário atual. Em seguida, ele chama o procedimento externo GetUserNameA como parte do procedimento 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

Exemplo 2

DllImportAttribute fornece uma maneira alternativa de usar funções no código não gerenciado. O exemplo a seguir declara uma função importada sem usar uma instrução 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

Compartilhar via