Angeben eines ZeichensatzesSpecifying a Character Set

Das DllImportAttribute.CharSet-Feld steuert das Marshallen von Zeichenfolgen und bestimmt, wie Plattformaufrufe Funktionsnamen in einer DLL finden.The DllImportAttribute.CharSet field controls string marshaling and determines how platform invoke finds function names in a DLL. In diesem Abschnitt werden beide Verhaltensweisen beschrieben.This topic describes both behaviors.

Einige APIs exportieren zwei Versionen von Funktionen, die Zeichenfolgenargumente verwenden: schmal (ANSI) und breit (Unicode).Some APIs export two versions of functions that take string arguments: narrow (ANSI) and wide (Unicode). Die Windows-API enthält z.B. die folgenden Einstiegspunktnamen für die MessageBox-Funktion:The Windows API, for instance, includes the following entry-point names for the MessageBox function:

  • MessageBoxAMessageBoxA

    Stellt einen 1-Byte-Zeichensatz im ANSI-Format zur Verfügung, der durch ein zum Namen des Einstiegspunkts hinzugefügten „A“ unterschieden wird.Provides 1-byte character ANSI formatting, distinguished by an "A" appended to the entry-point name. Aufrufe von MessageBoxA marshallen Zeichenfolgen immer im ANSI-Format.Calls to MessageBoxA always marshal strings in ANSI format.

  • MessageBoxWMessageBoxW

    Stellt einen 2-Byte-Zeichensatz im Unicode-Format zur Verfügung, der durch ein zum Namen des Einstiegspunkts hinzugefügten „W“ unterschieden wird.Provides 2-byte character Unicode formatting, distinguished by a "W" appended to the entry-point name. Aufrufe von MessageBoxW marshallen Zeichenfolgen immer im Unicode-Format.Calls to MessageBoxW always marshal strings in Unicode format.

Marshallen von Zeichenfolgen und NamensübereinstimmungString Marshaling and Name Matching

Das Feld CharSet akzeptiert die folgenden Werte:The CharSet field accepts the following values:

Ansi (Standardwert)Ansi (default value)

  • Marshallen von ZeichenfolgenString marshaling

    Plattformaufruf marshallt Zeichenfolgen aus dem verwalteten Format (Unicode) in das ANSI-Format.Platform invoke marshals strings from their managed format (Unicode) to ANSI format.

  • NamensübereinstimmungName matching

    Wenn das DllImportAttribute.ExactSpelling-Feld true entspricht, wie es standardmäßig in Visual Basic der Fall ist, sucht der Plattformaufruf nur nach dem von Ihnen angegebenen Namen.When the DllImportAttribute.ExactSpelling field is true, as it is by default in Visual Basic, platform invoke searches only for the name you specify. Wenn Sie z.B. MessageBox angeben, sucht der Plattformaufruf nach MessageBox und schlägt fehl, wenn er die exakte Schreibweise nicht finden kann.For example, if you specify MessageBox, platform invoke searches for MessageBox and fails when it cannot locate the exact spelling.

    Wenn das Feld ExactSpelling false ist, wie es standardmäßig in C++ und C# der Fall ist, sucht der Plattformaufruf zunächst nach dem unbeschädigten Alias (MessageBox) und dann nach dem beschädigten Namen (MessageBoxA), wenn der unbeschädigten Alias nicht gefunden wird.When the ExactSpelling field is false, as it is by default in C++ and C#, platform invoke searches for the unmangled alias first (MessageBox), then the mangled name (MessageBoxA) if the unmangled alias is not found. Beachten Sie, dass die Namensübereinstimmung des ANSI-Verhaltens sich von der Namensübereinstimmung des Unicode-Verhaltens unterscheidet.Notice that ANSI name-matching behavior differs from Unicode name-matching behavior.

Unicode

  • Marshallen von ZeichenfolgenString marshaling

    Der Plattformaufruf kopiert Zeichenfolgen aus dem verwalteten Format (Unicode) in Unicode-Format.Platform invoke copies strings from their managed format (Unicode) to Unicode format.

  • NamensübereinstimmungName matching

    Wenn das ExactSpelling-Feld true entspricht, wie es standardmäßig in Visual Basic der Fall ist, sucht der Plattformaufruf nur nach dem von Ihnen angegebenen Namen.When the ExactSpelling field is true, as it is by default in Visual Basic, platform invoke searches only for the name you specify. Wenn Sie z.B. MessageBox angeben, sucht der Plattformaufruf nach MessageBox und schlägt fehl, wenn er die exakte Schreibweise nicht finden kann.For example, if you specify MessageBox, platform invoke searches for MessageBox and fails if it cannot locate the exact spelling.

    Wenn das Feld ExactSpelling false ist, wie es standardmäßig in C++ und C# der Fall ist, sucht der Plattformaufruf zunächst nach dem beschädigten Namen (MessageBoxW) und dann nach dem unbeschädigten Alias (MessageBox), wenn der beschädigte Alias nicht gefunden wird.When the ExactSpelling field is false, as it is by default in C++ and C#, platform invoke searches for the mangled name first (MessageBoxW), then the unmangled alias (MessageBox) if the mangled name is not found. Beachten Sie, dass das Verhalten der Namensübereinstimmung von Unicode sich vom Verhalten der Namensübereinstimmung von ANSI unterscheidet.Notice that Unicode name-matching behavior differs from ANSI name-matching behavior.

Auto

  • Der Plattformaufruf basierend auf der Zielplattform zur Laufzeit wählt zwischen ANSI- und Unicode-Formaten.Platform invoke chooses between ANSI and Unicode formats at run time, based on the target platform.

Festlegen eines Zeichensatzes in Visual BasicSpecifying a Character Set in Visual Basic

Das folgende Beispiel deklariert die MessageBox-Funktion dreimal, wobei der Zeichensatz sich jedes Mal unterschiedlich verhält.The following example declares the MessageBox function three times, each time with different character-set behavior. Sie können das Verhalten des Zeichensatzes in Visual Basic angeben, indem Sie die Schlüsselwörter Ansi, Unicode oder Auto zur Deklarationsanweisung hinzufügen.You can specify character-set behavior in Visual Basic by adding the Ansi, Unicode, or Auto keyword to the declaration statement.

Wenn Sie das Zeichensatzschlüsselwort weglassen, wie es in der ersten Deklarationsanweisung der Fall ist, erfolgt das DllImportAttribute.CharSet-Feld standardmäßig im ANSI-Zeichensatz.If you omit the character-set keyword, as is done in the first declaration statement, the DllImportAttribute.CharSet field defaults to the ANSI character set. Die zweite und dritte Anweisung in diesem Beispiel geben einen Zeichensatz explizit mit einem Schlüsselwort an.The second and third statements in the example explicitly specify a character set with a keyword.

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

Festlegen eines Zeichensatzes in C# und C++Specifying a Character Set in C# and C++

Das DllImportAttribute.CharSet-Feld identifiziert den zugrunde liegenden Zeichensatz als ANSI oder Unicode.The DllImportAttribute.CharSet field identifies the underlying character set as ANSI or Unicode. Der Zeichensatz steuert, wie die Zeichenfolgenargumente an eine Methode gemarshallt werden sollen.The character set controls how string arguments to a method should be marshaled. Verwenden Sie eines der folgenden Formate, um den Zeichensatz anzugeben:Use one of the following forms to indicate the character set:

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

Im folgenden Beispiel werden drei verwaltete Definitionen der MessageBox-Funktion angezeigt, die einen Zeichensatz anzeigen.The following example shows three managed definitions of the MessageBox function attributed to specify a character set. Durch die Auslassung wird das Feld CharSet in der ersten Definition standardmäßig in ANSI-Zeichensatz verwandelt.In the first definition, by its omission, the CharSet field defaults to the ANSI character set.

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);

Siehe auchSee also