CA2205: Utilizar equivalentes administrados de la API Win32CA2205: Use managed equivalents of Win32 API

TypeNameTypeName UseManagedEquivalentsOfWin32ApiUseManagedEquivalentsOfWin32Api
Identificador de comprobaciónCheckId CA2205CA2205
CategoríaCategory Microsoft.UsageMicrosoft.Usage
Cambio problemáticoBreaking Change No trascendentalNon Breaking

MotivoCause

Una invocación de plataforma se define el método y existe un método con la funcionalidad equivalente en la biblioteca de clases de .NET Framework.A platform invoke method is defined and a method with the equivalent functionality exists in the .NET Framework class library.

Descripción de la reglaRule description

Una plataforma de invocación de método se usa para llamar a una función DLL no administrada y se define utilizando el System.Runtime.InteropServices.DllImportAttribute atributo, o la Declare palabra clave en Visual Basic.A platform invoke method is used to call an unmanaged DLL function and is defined using the System.Runtime.InteropServices.DllImportAttribute attribute, or the Declare keyword in Visual Basic. Método de invocación de una plataforma definida incorrectamente puede generar excepciones en tiempo de ejecución debido a problemas como una función con nombre incorrecto, una asignación de tipos de datos de valor devueltos y de parámetro y las especificaciones de campo incorrecto, como la convención de llamada y el carácter defectuosa conjunto.An incorrectly defined platform invoke method can lead to runtime exceptions because of issues such as a misnamed function, faulty mapping of parameter and return value data types, and incorrect field specifications, such as the calling convention and character set. Si está disponible, es más sencillo y menos propenso a errores llamar al método administrado equivalente que to definir y llamar directamente al método no administrado.If available, it is simpler and less error prone to call the equivalent managed method than to define and call the unmanaged method directly. Una llamada a una plataforma de invocar el método también pueden provocar problemas de seguridad adicionales que deban solucionarse.Calling a platform invoke method can also lead to additional security issues that need to be addressed.

Cómo corregir infraccionesHow to fix violations

Para corregir una infracción de esta regla, reemplace la llamada a la función no administrada con una llamada a su equivalente administrado.To fix a violation of this rule, replace the call to the unmanaged function with a call to its managed equivalent.

Cuándo Suprimir advertenciasWhen to suppress warnings

Suprima una advertencia de esta regla si el método de reemplazo sugerido no proporciona la funcionalidad necesaria.Suppress a warning from this rule if the suggested replacement method does not provide the needed functionality.

EjemploExample

El ejemplo siguiente se muestra una plataforma de invocación de definición de método que infringe la regla.The following example shows a platform invoke method definition that violates the rule. Además, las llamadas a la plataforma de invocación de método y se muestra el método administrado equivalente.In addition, the calls to the platform invoke method and the equivalent managed method are shown.

using System;
using System.Runtime.InteropServices;
using System.Text;

namespace UsageLibrary
{
   internal class NativeMethods
   {
      private NativeMethods() {}

      // The following method definition violates the rule.
      [DllImport("kernel32.dll", CharSet = CharSet.Unicode, 
          SetLastError = true)]
      internal static extern int ExpandEnvironmentStrings(
         string lpSrc, StringBuilder lpDst, int nSize);
   }

   public class UseNativeMethod
   {
      public void Test()
      {
         string environmentVariable = "%TEMP%";
         StringBuilder expandedVariable = new StringBuilder(100);

         // Call the unmanaged method.
         NativeMethods.ExpandEnvironmentStrings(
            environmentVariable, 
            expandedVariable, 
            expandedVariable.Capacity);

         // Call the equivalent managed method.
         Environment.ExpandEnvironmentVariables(environmentVariable);
      }
   }
}
Imports System
Imports System.Runtime.InteropServices
Imports System.Text

Namespace UsageLibrary

   Class NativeMethods

      Private Sub New()
      End Sub

      ' The following method definitions violate the rule.

      <DllImport("kernel32.dll", CharSet := CharSet.Unicode, _ 
         SetLastError := True)> _ 
      Friend Shared Function ExpandEnvironmentStrings _ 
         (lpSrc As String, lpDst As StringBuilder, nSize As Integer) _ 
         As Integer
      End Function

      Friend Declare Unicode Function ExpandEnvironmentStrings2 _ 
         Lib "kernel32.dll" Alias "ExpandEnvironmentStrings" _ 
         (lpSrc As String, lpDst As StringBuilder, nSize As Integer) _ 
         As Integer

   End Class

   Public Class UseNativeMethod

      Shared Sub Main()
      
         Dim environmentVariable As String = "%TEMP%"
         Dim expandedVariable As New StringBuilder(100)

         ' Call the unmanaged method.
         NativeMethods.ExpandEnvironmentStrings( _ 
            environmentVariable, _ 
            expandedVariable, _ 
            expandedVariable.Capacity)

         ' Call the unmanaged method.
         NativeMethods.ExpandEnvironmentStrings2( _ 
            environmentVariable, _ 
            expandedVariable, _ 
            expandedVariable.Capacity)

         ' Call the equivalent managed method.
         Environment.ExpandEnvironmentVariables(environmentVariable)

      End Sub

   End Class

End Namespace