CA1838: Avoid StringBuilder parameters for P/Invokes (Evitar los parámetros StringBuilder para los elementos P/Invoke)

  • Artículo
Propiedad Value
Identificador de la regla CA1838
Título Evitar los parámetros StringBuilder para los elementos P/Invoke
Categoría Rendimiento
La corrección es problemática o no problemática Poco problemático
Habilitado de forma predeterminada en .NET 8 No

Causa

P/Invoke tiene un parámetro StringBuilder.

Descripción de la regla

Al serializar StringBuilder siempre se crea una copia del búfer nativo, lo que da lugar a varias asignaciones para una llamada de P/Invoke. Para serializar StringBuilder como un parámetro P/Invoke, el runtime hará lo siguiente:

  • Asignar un búfer nativo.
  • Si es un parámetro In, copiar el contenido de StringBuilder en el búfer nativo.
  • Si es un parámetro Out, copiar el búfer nativo en una matriz administrada recién asignada.

De forma predeterminada, StringBuilder es In y Out.

Para obtener más información sobre la serialización de cadenas, vea Serialización predeterminada para cadenas.

Esta regla está deshabilitada de forma predeterminada porque puede requerir el análisis caso por caso de si la infracción es de interés y de refactorización potencialmente no trivial para solucionar la infracción. Los usuarios pueden habilitar explícitamente esta regla configurando su gravedad.

Cómo corregir infracciones

En general, corregir una infracción implica la modificación de P/Invoke y sus autores de la llamada para que utilicen un búfer en lugar de StringBuilder. Los detalles dependerán de los casos de uso de P/Invoke.

Este es un ejemplo para el escenario común de uso de StringBuilder como búfer de salida que va a rellenar la función nativa:

// Violation
[DllImport("MyLibrary", CharSet = CharSet.Unicode)]
private static extern void Foo(StringBuilder sb, ref int length);

public void Bar()
{
    int BufferSize = ...
    StringBuilder sb = new StringBuilder(BufferSize);
    int len = sb.Capacity;
    Foo(sb, ref len);
    string result = sb.ToString();
}

En los casos de uso en los que el búfer es pequeño y el código unsafe es aceptable, se puede usar stackalloc para asignar el búfer en la pila:

[DllImport("MyLibrary", CharSet = CharSet.Unicode)]
private static extern unsafe void Foo(char* buffer, ref int length);

public void Bar()
{
    int BufferSize = ...
    unsafe
    {
        char* buffer = stackalloc char[BufferSize];
        int len = BufferSize;
        Foo(buffer, ref len);
        string result = new string(buffer);
    }
}

En el caso de los búferes mayores, se puede asignar una nueva matriz como búfer:

[DllImport("MyLibrary", CharSet = CharSet.Unicode)]
private static extern void Foo([Out] char[] buffer, ref int length);

public void Bar()
{
    int BufferSize = ...
    char[] buffer = new char[BufferSize];
    int len = buffer.Length;
    Foo(buffer, ref len);
    string result = new string(buffer);
}

Cuando a menudo se llama a P/Invoke para búferes de mayor tamaño, ArrayPool<T> puede usarse para evitar las asignaciones repetidas y la presión de memoria que se incluye en ellos:

[DllImport("MyLibrary", CharSet = CharSet.Unicode)]
private static extern unsafe void Foo([Out] char[] buffer, ref int length);

public void Bar()
{
    int BufferSize = ...
    char[] buffer = ArrayPool<char>.Shared.Rent(BufferSize);
    try
    {
        int len = buffer.Length;
        Foo(buffer, ref len);
        string result = new string(buffer);
    }
    finally
    {
        ArrayPool<char>.Shared.Return(buffer);
    }
}

Si no se conoce el tamaño del búfer hasta el tiempo de ejecución, es posible que sea necesario crear el búfer de manera diferente en función del tamaño para evitar la asignación de búferes de gran tamaño con stackalloc.

En los ejemplos anteriores se utilizan caracteres anchos de 2 bytes (CharSet.Unicode). Si la función nativa usa caracteres de 1 byte (CharSet.Ansi), se puede utilizar un búfer byte en lugar de uno char. Por ejemplo:

[DllImport("MyLibrary", CharSet = CharSet.Ansi)]
private static extern unsafe void Foo(byte* buffer, ref int length);

public void Bar()
{
    int BufferSize = ...
    unsafe
    {
        byte* buffer = stackalloc byte[BufferSize];
        int len = BufferSize;
        Foo(buffer, ref len);
        string result = Marshal.PtrToStringAnsi((IntPtr)buffer);
    }
}

Si el parámetro también se usa como entrada, los búferes se deben rellenar con los datos de cadena con cualquier terminador nulo agregado explícitamente.

Cuándo suprimir las advertencias

Suprima una infracción de esta regla si no le preocupa el impacto en el rendimiento de la serialización de StringBuilder.

Supresión de una advertencia

Si solo quiere suprimir una única infracción, agregue directivas de preprocesador al archivo de origen para deshabilitar y volver a habilitar la regla.

#pragma warning disable CA1838
// The code that's violating the rule is on this line.
#pragma warning restore CA1838

Para deshabilitar la regla de un archivo, una carpeta o un proyecto, establezca su gravedad en none del archivo de configuración.

[*.{cs,vb}]
dotnet_diagnostic.CA1838.severity = none

Para obtener más información, consulte Procedimiento para suprimir advertencias de análisis de código.

Consulte también