在C#开发中，当我们需要获取Windows系统底层操作的错误详情时，FormatMessage API是一个非常实用的工具，它可以把系统错误码转换为人类可读的错误描述文本。下面我们就详细介绍在C#中调用这个API的完整方法。
FormatMessage API基本介绍
FormatMessage是Windows提供的一个系统API，位于kernel32.dll中，主要作用是根据错误码获取对应的错误描述信息，支持系统定义的错误码、模块自定义的错误码等多种场景，比单纯通过错误码判断错误原因要直观很多。
C#中声明FormatMessage API
在C#中调用非托管的Windows API需要使用PInvoke（平台调用）技术，首先我们需要在代码中声明FormatMessage函数和相关的常量、枚举。
相关常量和枚举定义
FormatMessage有多个标志位参数，我们需要先定义对应的常量：
using System;
using System.Runtime.InteropServices;
public class FormatMessageHelper
{
// FormatMessage的标志位常量
public const uint FORMAT_MESSAGE_ALLOCATE_BUFFER = 0x00000100;
public const uint FORMAT_MESSAGE_FROM_SYSTEM = 0x00001000;
public const uint FORMAT_MESSAGE_IGNORE_INSERTS = 0x00000200;
public const uint FORMAT_MESSAGE_FROM_HMODULE = 0x00000800;
// 语言ID常量，这里使用默认系统语言
public const uint LANG_NEUTRAL = 0x00;
public const uint SUBLANG_DEFAULT = 0x01;
public const uint FORMAT_MESSAGE_DEFAULT_LANGUAGE = (LANG_NEUTRAL << 10) | SUBLANG_DEFAULT;
}API函数声明
接下来声明FormatMessage函数和GetLastError函数，GetLastError用于获取最近一次系统操作的错误码：
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern uint FormatMessage(
uint dwFlags,
IntPtr lpSource,
uint dwMessageId,
uint dwLanguageId,
ref IntPtr lpBuffer,
uint nSize,
IntPtr Arguments
);
[DllImport("kernel32.dll")]
public static extern uint GetLastError();
[DllImport("kernel32.dll")]
public static extern IntPtr LocalFree(IntPtr hMem);调用FormatMessage获取系统错误信息
最常见的场景是获取系统操作的错误描述，我们可以结合GetLastError获取错误码，再调用FormatMessage转换为文本。
完整调用示例
public static string GetSystemErrorDescription(uint errorCode)
{
IntPtr bufferPtr = IntPtr.Zero;
try
{
// 调用FormatMessage，从系统获取错误描述，自动分配缓冲区
uint result = FormatMessage(
FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
IntPtr.Zero,
errorCode,
FORMAT_MESSAGE_DEFAULT_LANGUAGE,
ref bufferPtr,
0,
IntPtr.Zero
);
if (result == 0)
{
// 如果调用失败，返回未知错误提示
return $"无法获取错误码{errorCode}的描述信息";
}
// 将非托管内存中的字符串转换为托管字符串
string errorDescription = Marshal.PtrToStringUni(bufferPtr);
// 去除末尾的换行符等空白字符
return errorDescription?.Trim() ?? string.Empty;
}
finally
{
// 释放FormatMessage分配的缓冲区
if (bufferPtr != IntPtr.Zero)
{
LocalFree(bufferPtr);
}
}
}
// 使用示例
public static void TestGetError()
{
// 模拟一个不存在的错误码，或者先调用一个会失败的系统操作再获取错误码
uint testErrorCode = 2; // 系统错误码2表示"系统找不到指定的文件"
string description = GetSystemErrorDescription(testErrorCode);
Console.WriteLine($"错误码{testErrorCode}的描述：{description}");
// 也可以获取最近一次系统操作的错误码
uint lastError = GetLastError();
if (lastError != 0)
{
string lastErrorDesc = GetSystemErrorDescription(lastError);
Console.WriteLine($"最近一次系统错误码{lastError}的描述：{lastErrorDesc}");
}
}参数说明和注意事项
- dwFlags参数：常用组合是FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS，前者让API自动分配缓冲区，中间表示从系统错误码表获取信息，后者表示忽略消息中的插入序列。
- dwMessageId参数：就是要查询的错误码，可以是GetLastError返回的值，也可以是自定义的错误码。
- 内存释放：当使用FORMAT_MESSAGE_ALLOCATE_BUFFER标志时，API会通过LocalAlloc分配内存，调用完成后必须使用LocalFree释放，否则会造成内存泄漏。
- 字符集：声明时建议指定CharSet为Unicode，避免不同系统下的字符编码问题。
常见问题解决
如果调用FormatMessage返回0，说明调用失败，这时候可以再次调用GetLastError查看FormatMessage本身的错误原因。另外如果查询的是自定义模块的错误码，需要把dwFlags加上FORMAT_MESSAGE_FROM_HMODULE，并且lpSource参数传入对应模块的句柄。
C#FormatMessageAPI调用系统错误信息PInvoke修改时间：2026-05-29 04:34:15