Marshaling padrão para cadeias de caracteres

2025-06-19

Ambas as classes, System.String e System.Text.StringBuilder, têm comportamentos de marshaling semelhantes.

As cadeias de caracteres são empacotadas como um tipo de estilo BSTR COM ou como uma cadeia de caracteres terminada em nulo (uma matriz de caracteres que termina com um caractere nulo). Os caracteres dentro da cadeia de caracteres podem ser empacotados como Unicode (o padrão em sistemas Windows) ou ANSI.

Cadeias de caracteres usadas em interfaces

A tabela a seguir mostra as opções de marshaling para o tipo de dados Cadeia de Caracteres ao realizar marshaling como um argumento de método para um código não gerenciado. O atributo MarshalAsAttribute fornece vários valores de enumeração UnmanagedType para organizar cadeias de caracteres em interfaces COM.

Tipo de enumeração	Descrição do formato não gerenciado
`UnmanagedType.BStr` (padrão)	Um estilo `BSTR` COM com um comprimento prefixado e caracteres Unicode.
`UnmanagedType.LPStr`	Um ponteiro para uma matriz terminada em nulo de caracteres ANSI.
`UnmanagedType.LPWStr`	Um ponteiro para uma matriz terminada em nulo de caracteres Unicode.

Esta tabela se aplica a String. Para StringBuilder, as únicas opções permitidas são UnmanagedType.LPStr e UnmanagedType.LPWStr.

O exemplo a seguir mostra cadeias de caracteres declaradas na IStringWorker interface.

public interface IStringWorker
{
    void PassString1(string s);
    void PassString2([MarshalAs(UnmanagedType.BStr)] string s);
    void PassString3([MarshalAs(UnmanagedType.LPStr)] string s);
    void PassString4([MarshalAs(UnmanagedType.LPWStr)] string s);
    void PassStringRef1(ref string s);
    void PassStringRef2([MarshalAs(UnmanagedType.BStr)] ref string s);
    void PassStringRef3([MarshalAs(UnmanagedType.LPStr)] ref string s);
    void PassStringRef4([MarshalAs(UnmanagedType.LPWStr)] ref string s);
}

Public Interface IStringWorker
    Sub PassString1(s As String)
    Sub PassString2(<MarshalAs(UnmanagedType.BStr)> s As String)
    Sub PassString3(<MarshalAs(UnmanagedType.LPStr)> s As String)
    Sub PassString4(<MarshalAs(UnmanagedType.LPWStr)> s As String)
    Sub PassStringRef1(ByRef s As String)
    Sub PassStringRef2(<MarshalAs(UnmanagedType.BStr)> ByRef s As String)
    Sub PassStringRef3(<MarshalAs(UnmanagedType.LPStr)> ByRef s As String)
    Sub PassStringRef4(<MarshalAs(UnmanagedType.LPWStr)> ByRef s As String)
End Interface

O exemplo a seguir mostra a interface correspondente descrita em uma biblioteca de tipos.

interface IStringWorker : IDispatch
{
    HRESULT PassString1([in] BSTR s);
    HRESULT PassString2([in] BSTR s);
    HRESULT PassString3([in] LPStr s);
    HRESULT PassString4([in] LPWStr s);
    HRESULT PassStringRef1([in, out] BSTR *s);
    HRESULT PassStringRef2([in, out] BSTR *s);
    HRESULT PassStringRef3([in, out] LPStr *s);
    HRESULT PassStringRef4([in, out] LPWStr *s);
};

Cadeias de caracteres usadas na invocação de plataforma

Quando o CharSet é Unicode ou um argumento de cadeia de caracteres é explicitamente marcado como [MarshalAs(UnmanagedType.LPWSTR)] e a cadeia de caracteres é passada por valor (não ref ou out), a cadeia de caracteres é fixada e usada diretamente pelo código nativo. Caso contrário, a invocação de plataforma copia argumentos de cadeia de caracteres, convertendo-os do formato do .NET Framework (Unicode) para o formato não gerenciado da plataforma. As cadeias de caracteres são imutáveis e não são copiadas de volta da memória não gerenciada para a memória gerenciada quando a chamada é retornada.

O código nativo só é responsável por liberar a memória quando a cadeia de caracteres é passada por referência e atribui um novo valor. Caso contrário, o runtime do .NET é proprietário da memória e a liberará após a chamada.

A tabela a seguir lista as opções de marshaling para cadeias de caracteres ao realizar marshaling delas como um argumento de método de uma chamada de invocação de plataforma. O MarshalAsAttribute atributo fornece vários UnmanagedType valores de enumeração para processar cadeias de caracteres.

Tipo de enumeração	Descrição do formato não gerenciado
`UnmanagedType.AnsiBStr`	Um estilo `BSTR` COM com um comprimento prefixado e caracteres ANSI.
`UnmanagedType.BStr`	Um estilo `BSTR` COM com um comprimento prefixado e caracteres Unicode.
`UnmanagedType.LPStr` (padrão)	Um ponteiro para uma matriz terminada em nulo de caracteres ANSI.
`UnmanagedType.LPTStr`	Um ponteiro para uma matriz terminada em nulo de caracteres dependentes de plataforma.
`UnmanagedType.LPUTF8Str`	Um ponteiro para uma matriz terminada em nulo de caracteres codificados em UTF-8.
`UnmanagedType.LPWStr`	Um ponteiro para uma matriz terminada em nulo de caracteres Unicode.
`UnmanagedType.TBStr`	Um estilo `BSTR` COM com um comprimento prefixado e caracteres dependentes da plataforma.
`VBByRefStr`	Um valor que permite que o Visual Basic altere uma cadeia de caracteres em código não gerenciado e tenha os resultados refletidos no código gerenciado. Esse valor tem suporte apenas para invocação de plataforma. Esse é o valor padrão no Visual Basic para `ByVal` cadeias de caracteres.

Esta tabela se aplica a String. Para StringBuilder, as únicas opções permitidas são LPStr, LPTStre LPWStr.

A definição de tipo a seguir mostra o uso correto de MarshalAsAttribute para chamadas de invocação de plataforma.

class StringLibAPI
{
    [DllImport("StringLib.dll")]
    public static extern void PassLPStr([MarshalAs(UnmanagedType.LPStr)] string s);
    [DllImport("StringLib.dll")]
    public static extern void PassLPWStr([MarshalAs(UnmanagedType.LPWStr)] string s);
    [DllImport("StringLib.dll")]
    public static extern void PassLPTStr([MarshalAs(UnmanagedType.LPTStr)] string s);
    [DllImport("StringLib.dll")]
    public static extern void PassLPUTF8Str([MarshalAs(UnmanagedType.LPUTF8Str)] string s);
    [DllImport("StringLib.dll")]
    public static extern void PassBStr([MarshalAs(UnmanagedType.BStr)] string s);
    [DllImport("StringLib.dll")]
    public static extern void PassAnsiBStr([MarshalAs(UnmanagedType.AnsiBStr)] string s);
    [DllImport("StringLib.dll")]
    public static extern void PassTBStr([MarshalAs(UnmanagedType.TBStr)] string s);
}

Class StringLibAPI
    Public Declare Auto Sub PassLPStr Lib "StringLib.dll" (
        <MarshalAs(UnmanagedType.LPStr)> s As String)
    Public Declare Auto Sub PassLPWStr Lib "StringLib.dll" (
        <MarshalAs(UnmanagedType.LPWStr)> s As String)
    Public Declare Auto Sub PassLPTStr Lib "StringLib.dll" (
        <MarshalAs(UnmanagedType.LPTStr)> s As String)
    Public Declare Auto Sub PassLPUTF8Str Lib "StringLib.dll" (
        <MarshalAs(UnmanagedType.LPUTF8Str)> s As String)
    Public Declare Auto Sub PassBStr Lib "StringLib.dll" (
        <MarshalAs(UnmanagedType.BStr)> s As String)
    Public Declare Auto Sub PassAnsiBStr Lib "StringLib.dll" (
        <MarshalAs(UnmanagedType.AnsiBStr)> s As String)
    Public Declare Auto Sub PassTBStr Lib "StringLib.dll" (
        <MarshalAs(UnmanagedType.TBStr)> s As String)
End Class

Cadeias de caracteres usadas em estruturas

Cadeias de caracteres são membros válidos de estruturas; no entanto, StringBuilder os buffers são inválidos em estruturas. A tabela a seguir mostra as opções de marshaling para o tipo de dados String, quando é realizado o marshaling desse tipo como um campo. O atributo MarshalAsAttribute fornece vários valores de enumeração UnmanagedType para converter strings em um campo.

Tipo de enumeração	Descrição do formato não gerenciado
`UnmanagedType.BStr`	Um estilo `BSTR` COM com um comprimento prefixado e caracteres Unicode.
`UnmanagedType.LPStr` (padrão)	Um ponteiro para uma matriz terminada em nulo de caracteres ANSI.
`UnmanagedType.LPTStr`	Um ponteiro para uma matriz terminada em nulo de caracteres dependentes de plataforma.
`UnmanagedType.LPUTF8Str`	Um ponteiro para uma matriz terminada em nulo de caracteres codificados em UTF-8.
`UnmanagedType.LPWStr`	Um ponteiro para uma matriz terminada em nulo de caracteres Unicode.
`UnmanagedType.ByValTStr`	Uma matriz de comprimento fixo de caracteres; o tipo da matriz é determinado pelo conjunto de caracteres da estrutura que contém.

O ByValTStr tipo é usado para matrizes de caracteres embutidas e de comprimento fixo que aparecem dentro de uma estrutura. Outros tipos se aplicam a referências de cadeia de caracteres contidas em estruturas que contêm ponteiros para cadeias de caracteres.

O argumento CharSet do StructLayoutAttribute, quando aplicado à estrutura que o contém, determina o formato de caracteres das cadeias nas estruturas. As estruturas de exemplo a seguir contêm referências de cadeia de caracteres e cadeias de caracteres embutidas, bem como caracteres ANSI, Unicode e dependentes de plataforma. A representação dessas estruturas em uma biblioteca de tipos é mostrada no seguinte código C++:

struct StringInfoA
{
    char *  f1;
    char    f2[256];
};

struct StringInfoW
{
    WCHAR * f1;
    WCHAR   f2[256];
    BSTR    f3;
};

struct StringInfoT
{
    TCHAR * f1;
    TCHAR   f2[256];
};

O exemplo a seguir mostra como usar a MarshalAsAttribute para definir a mesma estrutura em diferentes formatos.

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi)]
struct StringInfoA
{
    [MarshalAs(UnmanagedType.LPStr)] public string f1;
    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)] public string f2;
}

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
struct StringInfoW
{
    [MarshalAs(UnmanagedType.LPWStr)] public string f1;
    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)] public string f2;
    [MarshalAs(UnmanagedType.BStr)] public string f3;
}

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]
struct StringInfoT
{
    [MarshalAs(UnmanagedType.LPTStr)] public string f1;
    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)] public string f2;
}

<StructLayout(LayoutKind.Sequential, CharSet := CharSet.Ansi)> _
Structure StringInfoA
    <MarshalAs(UnmanagedType.LPStr)> Public f1 As String
    <MarshalAs(UnmanagedType.ByValTStr, SizeConst := 256)> _
    Public f2 As String
End Structure

<StructLayout(LayoutKind.Sequential, CharSet := CharSet.Unicode)> _
Structure StringInfoW
    <MarshalAs(UnmanagedType.LPWStr)> Public f1 As String
    <MarshalAs(UnmanagedType.ByValTStr, SizeConst := 256)> _
    Public f2 As String
<MarshalAs(UnmanagedType.BStr)> Public f3 As String
End Structure

<StructLayout(LayoutKind.Sequential, CharSet := CharSet.Auto)> _
Structure StringInfoT
    <MarshalAs(UnmanagedType.LPTStr)> Public f1 As String
    <MarshalAs(UnmanagedType.ByValTStr, SizeConst := 256)> _
    Public f2 As String
End Structure

Buffers de cadeia de caracteres de comprimento fixo

Em algumas circunstâncias, um buffer de caracteres de comprimento fixo deve ser passado para um código não gerenciado para ser manipulado. Simplesmente passar uma cadeia de caracteres não funciona nesse caso porque o destinatário não pode modificar o conteúdo do buffer passado. Mesmo que a cadeia de caracteres seja passada por referência, não há como inicializar o buffer para um determinado tamanho.

A solução é passar um byte[] ou char[], dependendo da codificação esperada, como o argumento em vez de um String. A matriz, quando marcada com [Out], pode ser desreferenciada e modificada pelo destinatário, desde que não exceda a capacidade da matriz alocada.

Por exemplo, a função de API do Windows GetWindowText (definida em winuser.h) requer que o chamador passe um buffer de caracteres de comprimento fixo para o qual a função grava o texto da janela. O lpString argumento aponta para um buffer de tamanho nMaxCountalocado pelo chamador. Espera-se que o chamador aloque o buffer e defina o nMaxCount argumento para o tamanho do buffer alocado. O exemplo a seguir mostra a declaração da função GetWindowText como definido em winuser.h.

int GetWindowText(
    HWND hWnd,        // Handle to window or control.
    LPTStr lpString,  // Text buffer.
    int nMaxCount     // Maximum number of characters to copy.
);

Um char[] pode ser desreferenciado e modificado pelo destinatário. O exemplo de código a seguir demonstra como ArrayPool<char> pode ser usado para pré-alocar um char[].

using System;
using System.Buffers;
using System.Runtime.InteropServices;

internal static class NativeMethods
{
    [DllImport("User32.dll", CharSet = CharSet.Unicode)]
    public static extern void GetWindowText(IntPtr hWnd, [Out] char[] lpString, int nMaxCount);
}

public class Window
{
    internal IntPtr h;        // Internal handle to Window.
    public string GetText()
    {
        char[] buffer = ArrayPool<char>.Shared.Rent(256 + 1);
        NativeMethods.GetWindowText(h, buffer, buffer.Length);
        return new string(buffer);
    }
}

Imports System
Imports System.Buffers
Imports System.Runtime.InteropServices

Friend Class NativeMethods
    Public Declare Auto Sub GetWindowText Lib "User32.dll" _
        (hWnd As IntPtr, <Out> lpString() As Char, nMaxCount As Integer)
End Class

Public Class Window
    Friend h As IntPtr ' Friend handle to Window.
    Public Function GetText() As String
        Dim buffer() As Char = ArrayPool(Of Char).Shared.Rent(256 + 1)
        NativeMethods.GetWindowText(h, buffer, buffer.Length)
        Return New String(buffer)
   End Function
End Class

Outra solução é passar um StringBuilder como argumento em vez de um String. Um buffer criado ao realizar marshaling de um StringBuilder pode ser desreferenciado e modificado pelo receptor, contanto que não exceda a capacidade de StringBuilder. Ele também pode ser inicializado em um comprimento fixo. Por exemplo, se você inicializar um buffer de StringBuilder em uma capacidade de N, o marshaler fornecerá um buffer com (N+ 1) caracteres de tamanho. O +1 explica o fato de que a cadeia de caracteres não gerenciada tem um terminador nulo enquanto StringBuilder não tem.

Observação

Em geral, não é recomendável passar StringBuilder argumentos se você estiver preocupado com o desempenho. Para obter mais informações, consulte parâmetros de cadeia de caracteres.

Compartilhar via

Marshaling padrão para cadeias de caracteres

Cadeias de caracteres usadas em interfaces

Cadeias de caracteres usadas na invocação de plataforma

Cadeias de caracteres usadas em estruturas

Buffers de cadeia de caracteres de comprimento fixo

Consulte também

Comentários

Recursos adicionais