CA2205: Use managed equivalents of Win32 API
Note
This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
| Item | Value |
|---|---|
| TypeName | UseManagedEquivalentsOfWin32Api |
| CheckId | CA2205 |
| Category | Microsoft.Usage |
| Breaking Change | Non Breaking |
Cause
A platform invoke method is defined and a method with the equivalent functionality exists in the .NET Framework class library.
Rule Description
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. 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. If available, it is generally simpler and less error prone to call the equivalent managed method than to define and call the unmanaged method directly. Calling a platform invoke method can also lead to additional security issues that need to be addressed.
How to Fix Violations
To fix a violation of this rule, replace the call to the unmanaged function with a call to its managed equivalent.
When to Suppress Warnings
Suppress a warning from this rule if the suggested replacement method does not provide the needed functionality.
Example
The following example shows a platform invoke method definition that violates the rule. 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
Related Rules
CA1404: Call GetLastError immediately after P/Invoke
CA1060: Move P/Invokes to NativeMethods class
CA1400: P/Invoke entry points should exist