CA2205：必須使用 Win32 API 的 Managed 對應項
型別名稱 |
UseManagedEquivalentsOfWin32Api |
CheckId |
CA2205 |
分類 |
Microsoft.Usage |
中斷變更 |
不中斷 |
原因
已定義平台叫用方法，而且 .NET Framework 類別庫 (Class Library) 中有具同等功能的方法存在。
規則描述
平台叫用方法會用於呼叫 Unmanaged DLL 函式，而且此方法是使用 DllImportAttribute 屬性 (Attribute) 或 Visual Basic 中的 Declare 關鍵字所定義。未正確定義的平台叫用方法會造成執行階段例外狀況 (Exception)，原因在於諸如命名錯誤的函式、參數與傳回值資料型別的錯誤對應，以及不正確的欄位規格 (如呼叫慣例 (Calling Convention) 和字元集 (Character Set)) 等問題。如果可以的話，呼叫對等的 Managed 方法比起直接定義並呼叫 Unmanaged 方法，通常較為簡單且較不易發生錯誤。呼叫平台叫用方法也會造成其他需要加以處理的安全性問題。
如何修正違規
若要修正此規則的違規情形，請將 Unmanaged 函式的呼叫替換為 Managed 對等用法的呼叫。
隱藏警告的時機
如果建議的取代方法未提供需要的功能，請隱藏這項規則的警告。
範例
下列範例會顯示違反規則的平台叫用方法定義。此外，還會顯示平台叫用方法的呼叫和對等的 Managed 方法。
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
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);
}
}
}
相關規則
CA1404：必須在 P/Invoke 之後立即呼叫 GetLastError