Compartir a través de

Especificar un conjunto de caracteres

El campo DllImportAttribute.CharSet controla la serialización de cadenas y determina cómo la invocación de plataforma busca nombres de función en un archivo DLL. En este tema se describen ambos comportamientos.

Algunas API exportan dos versiones de funciones que toman argumentos de cadena: narrow (ANSI) y wide (Unicode). La API de Windows, por ejemplo, incluye los siguientes nombres de punto de entrada para la función MessageBox :

  • MessageBoxA

    Proporciona formato ANSI de 1 byte, distintivo por un "A" anexado al nombre del punto de entrada. Las llamadas a MessageBoxA siempre serializan las cadenas en formato ANSI.

  • MessageBoxW

    Proporciona formato Unicode de caracteres de 2 bytes, distintivo por un "W" anexado al nombre del punto de entrada. Las llamadas a MessageBoxW siempre serializan las cadenas en formato Unicode.

Serialización de cadenas y coincidencia de nombres

El CharSet campo acepta los siguientes valores:

Ansi (valor predeterminado)

  • Serialización de cadenas

    La invocación de plataforma serializa las cadenas del formato administrado (Unicode) al formato ANSI.

  • Coincidencia de nombres

    Cuando el DllImportAttribute.ExactSpelling campo es true, como está de forma predeterminada en Visual Basic, la invocación de plataforma solo busca el nombre que especifique. Por ejemplo, si especifica MessageBox, la invocación de plataforma busca MessageBox y produce un error cuando no puede encontrar la ortografía exacta.

    Si el campo ExactSpelling es false, como sucede de forma predeterminada en C++ y C#, la invocación de plataforma busca primero el alias no alterado (MessageBox) y, luego, el nombre alterado (MessageBoxA) en el caso de que no se encuentre el alias no alterado. Observe que el comportamiento de coincidencia de nombres ANSI difiere del comportamiento de coincidencia de nombres Unicode.

Unicode

  • Serialización de cadenas

    La invocación de plataforma copia las cadenas del formato administrado (Unicode) al formato Unicode.

  • Coincidencia de nombres

    Cuando el ExactSpelling campo es true, como está de forma predeterminada en Visual Basic, la invocación de plataforma solo busca el nombre que especifique. Por ejemplo, si especifica MessageBox, la invocación de plataforma busca MessageBox y produce un error si no puede encontrar la ortografía exacta.

    Cuando el ExactSpelling campo es false, como está de forma predeterminada en C++ y C#, la invocación de plataforma busca primero el nombre mutilado (MessageBoxW), luego, el alias sin modificar (MessageBox) si no se encuentra el nombre mutilado. Observe que el comportamiento de coincidencia de nombres Unicode difiere del comportamiento de coincidencia de nombres ANSI.

Auto

  • La invocación de plataforma elige entre formatos ANSI y Unicode en tiempo de ejecución, en función de la plataforma de destino.

Especificación de un juego de caracteres en Visual Basic

Puede especificar el comportamiento del juego de caracteres en Visual Basic agregando las palabras clave Ansi, Unicode o Auto a la instrucción de declaración. Si omite la palabra clave de juego de caracteres, el DllImportAttribute.CharSet campo tiene como valor predeterminado el juego de caracteres ANSI.

En el ejemplo siguiente se declara la función MessageBox tres veces, cada vez con un comportamiento diferente del juego de caracteres. La primera instrucción omite la palabra clave de juego de caracteres, por lo que el juego de caracteres tiene como valor predeterminado ANSI. Las instrucciones segunda y tercera especifican explícitamente un juego de caracteres con una palabra clave .

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 un juego de caracteres en C# y C++

El DllImportAttribute.CharSet campo identifica el juego de caracteres subyacente como ANSI o Unicode. El juego de caracteres controla cómo se deben serializar los argumentos de cadena para un método. Use uno de los formatos siguientes para indicar el juego 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)]

En el ejemplo siguiente se muestran tres definiciones administradas de la función MessageBox con atributos para especificar un juego de caracteres. En la primera definición, por su omisión, el CharSet campo tiene como valor predeterminado el juego 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 también