Compartilhar via

Especificar um conjunto de caracteres

O campo DllImportAttribute.CharSet controla o marshalling de cadeia de caracteres e determina como a invocação de plataforma localiza os nomes de função em uma DLL. Este tópico descreve ambos os comportamentos.

Algumas APIs exportam duas versões de funções que aceitam strings como argumentos: estreita (ANSI) e ampla (Unicode). A API do Windows, por exemplo, inclui os seguintes nomes de ponto de entrada para a MessageBox função:

  • MessageBoxA

    Fornece formatação ANSI de caractere de 1 byte, distinguida por um "A" acrescentado ao nome do ponto de entrada. Chamadas para MessageBoxA sempre encaminham cadeias de caracteres no formato ANSI.

  • MessageBoxW

    Fornece formatação Unicode de caractere de 2 bytes, distinguida por um "W" acrescentado ao nome do ponto de entrada. Chamadas para MessageBoxW sempre marshalam strings no formato Unicode.

Marshalling de cadeia de caracteres e correspondência de nomes

O CharSet campo aceita os seguintes valores:

Ansi (valor padrão)

  • Marshalling de cadeia de caracteres

    A invocação de plataforma realiza marshaling das cadeias de caracteres de seu formato gerenciado (Unicode) para o formato ANSI.

  • Correspondência de nomes

    Quando o campo DllImportAttribute.ExactSpelling está true, como é padrão no Visual Basic, a invocação de plataforma busca apenas pelo nome especificado. Por exemplo, se você especificar MessageBox, o invocador da plataforma procurará por MessageBox e falhará quando não conseguir localizar a correspondência exata.

    Quando o ExactSpelling campo é false, como é por padrão em C++ e C#, a plataforma invoca pesquisas para o alias não mutilado primeiro (MessageBox), em seguida, o nome mutilado (MessageBoxA) se o alias não mutilado não for encontrado. Observe que o comportamento de correspondência de nomes ANSI difere do comportamento de correspondência de nomes Unicode.

Unicode

  • Marshalling de cadeia de caracteres

    A invocação de plataforma copia as cadeias de caracteres de seu formato gerenciado (Unicode) para o formato Unicode.

  • Correspondência de nomes

    Quando o campo ExactSpelling está true, como é padrão no Visual Basic, a invocação de plataforma busca apenas pelo nome especificado. Por exemplo, se você especificar MessageBox, o mecanismo de invocação da plataforma procurará por MessageBox e falhará se não conseguir localizar a grafia exata.

    Quando o ExactSpelling campo é false, como é por padrão em C++ e C#, a plataforma invoca pesquisas para o nome mutilado primeiro (MessageBoxW), em seguida, o alias não mutilado (MessageBox) se o nome mutilado não for encontrado. Observe que o comportamento de correspondência de nomes Unicode difere do comportamento de correspondência de nomes ANSI.

Auto

  • A invocação de plataforma escolhe entre os formatos ANSI e Unicode em runtime, com base na plataforma de destino.

Especificar um conjunto de caracteres no Visual Basic

Você pode especificar o comportamento do conjunto de caracteres no Visual Basic adicionando a palavra-chave Ansi, Unicode ou Auto à instrução de declaração. Se você omitir a palavra-chave de conjunto de caracteres, o DllImportAttribute.CharSet campo usará como padrão o conjunto de caracteres ANSI.

O exemplo a seguir declara a MessageBox função três vezes, cada vez com um comportamento diferente do conjunto de caracteres. A primeira instrução omite a palavra-chave de conjunto de caracteres, portanto o conjunto de caracteres padrão é ANSI. A segunda e a terceira instruções especificam explicitamente um conjunto de caracteres com uma palavra-chave.

Friend Class NativeMethods
    Friend Declare Function MessageBoxA Lib "user32.dll" (
        ByVal hWnd As IntPtr,
        ByVal lpText As String,
        ByVal lpCaption As String,
        ByVal uType As UInteger) As Integer

    Friend Declare Unicode Function MessageBoxW Lib "user32.dll" (
        ByVal hWnd As IntPtr,
        ByVal lpText As String,
        ByVal lpCaption As String,
        ByVal uType As UInteger) As Integer

    Friend Declare Auto Function MessageBox Lib "user32.dll" (
        ByVal hWnd As IntPtr,
        ByVal lpText As String,
        ByVal lpCaption As String,
        ByVal uType As UInteger) As Integer
End Class

Especificar um conjunto de caracteres em C# e C++

O DllImportAttribute.CharSet campo identifica o conjunto de caracteres subjacente como ANSI ou Unicode. O conjunto de caracteres controla como deve ser realizado o marshalling dos argumentos da cadeia de caracteres para um método. Use um dos seguintes formulários para indicar o conjunto de caracteres:

[DllImport("DllName", CharSet = CharSet.Ansi)]
[DllImport("DllName", CharSet = CharSet.Unicode)]
[DllImport("DllName", CharSet = CharSet.Auto)]

[DllImport("DllName", CharSet = CharSet::Ansi)]
[DllImport("DllName", CharSet = CharSet::Unicode)]
[DllImport("DllName", CharSet = CharSet::Auto)]

O exemplo a seguir mostra três definições gerenciadas da MessageBox função atribuídas para especificar um conjunto de caracteres. Na primeira definição, por sua omissão, o campo CharSet usa como padrão o conjunto de caracteres ANSI.

using System;
using System.Runtime.InteropServices;

internal static class NativeMethods
{
    [DllImport("user32.dll")]
    internal static extern int MessageBoxA(
        IntPtr hWnd, string lpText, string lpCaption, uint uType);

    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
    internal static extern int MessageBoxW(
        IntPtr hWnd, string lpText, string lpCaption, uint uType);

    [DllImport("user32.dll", CharSet = CharSet.Auto)]
    internal static extern int MessageBox(
        IntPtr hWnd, string lpText, string lpCaption, uint uType);
}

typedef void* HWND;

// Can use MessageBox or MessageBoxA.
[DllImport("user32")]
extern "C" int MessageBox(
    HWND hWnd, String* lpText, String* lpCaption, unsigned int uType);

// Can use MessageBox or MessageBoxW.
[DllImport("user32", CharSet = CharSet::Unicode)]
extern "C" int MessageBoxW(
    HWND hWnd, String* lpText, String* lpCaption, unsigned int uType);

// Must use MessageBox.
[DllImport("user32", CharSet = CharSet::Auto)]
extern "C" int MessageBox(
    HWND hWnd, String* lpText, String* lpCaption, unsigned int uType);

Consulte também

  • Last updated on