Declaração de declaração

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

Observações

Às vezes, você precisa chamar um procedimento definido em um arquivo (como uma DLL ou recurso de código) fora do seu projeto. Quando você fizer 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 que ele usa. A Declare declaração cria uma referência a um procedimento externo e fornece essas informações necessárias.

Você pode usar Declare apenas no nível do módulo. Isso significa que o contexto da declaração para uma referência externa deve ser uma classe, estrutura ou módulo 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 seus níveis de acesso com os modificadores de acesso.

Regras

• Atributos. Você pode aplicar atributos a uma referência externa. Qualquer atributo que você aplicar terá efeito somente em seu projeto, não no arquivo externo.

• Modificadores. Os procedimentos externos são implicitamente partilhados. Não é possível usar a Shared palavra-chave ao declarar uma referência externa e não é possível alterar seu status compartilhado.

  Um procedimento externo não pode participar da substituição, implementar membros da interface ou manipular eventos. Assim, você não pode usar a Overridespalavra-chave , Overridable, NotOverridable, MustOverrideImplements, , ou Handles em uma Declare instrução.

• Nome do procedimento externo. Não é necessário 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 Alias cláusula para especificar o nome do ponto de entrada. Isso pode ser útil se o procedimento externo tiver o mesmo nome que um modificador reservado do Visual Basic ou uma variável, procedimento ou qualquer outro elemento de programação no mesmo escopo.

  Nota

  Os nomes de ponto de entrada na maioria das DLLs diferenciam maiúsculas de minúsculas.

• Número do procedimento externo. Como alternativa, você pode usar uma Alias cláusula para especificar o número ordinal do ponto de entrada dentro da tabela de exportação do arquivo externo. Para fazer isso, você começa aliasname com um sinal numérico (#). 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 de parâmetros. Se Option Strict for On, você deve especificar 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. No parameterlist, você usa uma As cláusula para especificar o tipo de dados do argumento a ser passado para cada parâmetro.

  Nota

  Se o procedimento externo não foi escrito para o .NET Framework, você deve tomar cuidado para que os tipos de dados correspondam. Por exemplo, se você declarar uma referência externa a um procedimento do Visual Basic 6.0 com um Integer parâmetro (16 bits no Visual Basic 6.0), você deve identificar o argumento correspondente como Short na Declare instrução, porque 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 um 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.

  Nota

  O compilador do Visual Basic não verifica se seus tipos de dados são compatíveis com os do procedimento externo. Se houver uma incompatibilidade, o common language runtime gerará uma MarshalDirectiveException exceção em 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 no parameterlist, o compilador do Visual Basic converte o argumento correspondente para o tipo de dados de objeto. Da mesma forma, se você não especificar returntype, o compilador considerará o tipo de dados de retorno como Object.

  Nota

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

Comportamento

• Âmbito. Uma referência externa está no escopo em toda a sua classe, estrutura ou módulo.

• Duração. Uma referência externa tem o mesmo tempo de vida que a classe, estrutura ou módulo em que é declarada.

• Chamando um procedimento externo. Você chama um procedimento externo da mesma forma que chama um Function ou Sub procedimento: usando-o em uma expressão se retornar um valor, ou especificando-o em uma instrução Call se não retornar um valor.

  Você passa argumentos para o procedimento externo exatamente como especificado na parameterlistDeclare instrução. Não leve em conta como os parâmetros foram originalmente declarados no arquivo externo. Da mesma forma, se houver um valor de retorno, use-o Declare exatamente como especificado na returntype instrução.

• Conjuntos de caracteres. Você pode especificar como charsetmodifier o Visual Basic deve organizar cadeias de caracteres quando ele chama o procedimento externo. O Ansi modificador direciona o Visual Basic para empacotar todas as cadeias de caracteres para valores ANSI, e o Unicode modificador direciona para marshal todas as cadeias de caracteres para valores Unicode. O Auto modificador direciona o Visual Basic para organizar cadeias de caracteres de acordo com as regras do .NET Framework com base na referência nameexterna ou aliasname se especificado. O valor predefinido é Ansi.

  charsetmodifier também especifica como o Visual Basic deve procurar o procedimento externo dentro de seu arquivo externo. Ansi e Unicode ambos direcionam o Visual Basic para procurá-lo sem modificar seu nome durante a pesquisa. Auto direciona o Visual Basic para determinar o conjunto de caracteres base da plataforma de 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 de nome. Se isso falhar, acrescente "W" ao final do nome do procedimento externo e pesquise-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 pesquise-o novamente.

• Mecanismo. Visual Basic usa o mecanismo de invocação da plataforma .NET Framework (PInvoke) para resolver e acessar procedimentos externos. A Declare instrução e a DllImportAttribute classe usam esse mecanismo automaticamente, e você não precisa de nenhum conhecimento de PInvoke. Para obter mais informações, consulte Passo a passo: chamando APIs do Windows.

Exemplo 1

O exemplo a seguir declara uma referência externa a um Function procedimento que retorna o nome de usuário atual. Em seguida, chama o procedimento GetUserNameA externo como parte do getUser procedimento.

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

O DllImportAttribute fornece uma maneira alternativa de usar funções em código não gerenciado. O exemplo a seguir declara uma função importada sem usar uma Declare instrução.

' 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

Consulte também

• LastDllError
• Instrução Imports (.NET Namespace and Type)
• Endereço do Operador
• Instrução de função
• Subdeclaração
• Lista de parâmetros
• Declaração de Chamada
• Passo a passo: Chamando APIs do Windows