使用 API 清除控制台屏幕

 下载示例代码

我之前在我的博客 Just Like a Magic.  上写过这篇文章。

• 概述
• 目录
• 引言
• GetStdHandle() 函数
• 关于封送的说明
• GetConsoleScreenBufferInfo() 函数
• 关于内存管理的说明
• 内存内部概览
• FillConsoleOutputCharacter() 函数
• SetConsoleCursorPosition() 函数
• 整合
• 清除控制台屏幕
• .NET 库内部概览
• 参考文献
• 代码示例（Tiny Console Library）
• 总结 

请确保 .NET 2.0 及更高版本中的 System.Console.Clear() 方法最初调用这四个函数——以及更多函数。 

HANDLE GetStdHandle(
  DWORD nStdHandle
); 

• STD_INPUT_HANDLE = -10
  指定标准输入设备（流）。
• STD_OUTPUT_HANDLE = -11
  指定标准输出设备（流）。
• STD_ERROR_HANDLE = -12
  指定标准错误设备（流）。它始终是输出设备（流）。

PInvoke 是 Platform Invocations 的缩写。它是 .NET 与其“女友”Win32 API 进行互操作的机制。

[DllImport("Kernel32.dll")]
public static extern IntPtr GetStdHandle(int nStdHandle); 

控制台应用程序只有一个输出句柄（输入和错误设备也一样），因此请勿使用 CloseHandle() 函数关闭已打开的句柄，否则将导致您无法再向控制台写入，除非您重新打开它。

参考部分可以找到描述封送过程和 Win32 数据类型的良好资源。

托管代码是运行在 CLR（通用语言运行时）中的 .NET 代码，因为 CLR 管理和控制此代码。相反，非托管代码是指除托管代码以外的代码。您可以在 .NET 中编写在 CLR 外部运行的代码，例如直接内存管理，并且该代码被称为不安全代码，因为它容易出错并可能导致不可预测的行为。此外，MC++ 允许您将非托管代码与托管代码一起编写。

BOOL GetConsoleScreenBufferInfo(
  HANDLE hConsoleOutput,
  [out] SCREEN_BUFFER_INFO lpConsoleScreenBufferInfo
);

struct CONSOLE_SCREEN_BUFFER_INFO {
  COORD dwSize;
  COORD dwCursorPosition;
  WORD wAttributes;
  SMALL_RECT srWindow;
  COORD dwMaximumWindowSize;
}

struct COORD {
  SHORT X;
  SHORT Y;
}

struct SMALL_RECT {
  SHORT Left;
  SHORT Top;
  SHORT Right;
  SHORT Bottom;
}

• 控制台屏幕缓冲区的大小，以字符行和列为单位。
• 控制台屏幕中的光标位置，以字符行和列为单位。
• 写入控制台的字符特征，例如前景色和背景色。
• 控制台窗口的位置和边界。
• 考虑到字体大小和屏幕缓冲区大小，控制台窗口的最大尺寸。

什么是屏幕缓冲区和窗口大小，它们之间有什么区别？启动命令提示符，右键单击任务栏中的图标，然后在属性对话框中转到“布局”选项卡。花些时间玩弄此选项卡中的值。窗口大小是控制台窗口的大小——就像任何其他窗口一样。屏幕缓冲区大小决定了控制台屏幕可以容纳的文本量，因此您总是会看到垂直滚动条，因为缓冲区高度大于窗口高度。

[DllImport("Kernel32.dll")]
public static extern int GetConsoleScreenBufferInfo
    (IntPtr hConsoleOutput,
    out CONSOLE_SCREEN_BUFFER_INFO lpConsoleScreenBufferInfo);

[StructLayout(LayoutKind.Sequential)]
public struct CONSOLE_SCREEN_BUFFER_INFO
{
    public COORD dwSize;
    public COORD dwCursorPosition;
    public ushort wAttributes;
    public SMALL_RECT srWindow;
    public COORD dwMaximumWindowSize;
}

[StructLayout(LayoutKind.Sequential)]
public struct COORD
{
    public short X;
    public short Y;
}

[StructLayout(LayoutKind.Sequential)]
public struct SMALL_RECT
{
    public short Left;
    public short Top;
    public short Right;
    public short Bottom;
}

BOOL 定义为 32 位有符号整数，因此我们已将函数的返回值封送为 Int32，而不是 Boolean，因为 Boolean 只占用 4 位。它与 Boolean 配合使用效果很好，但使用 Int32 更好。不过，如果您想使用布尔值，用 MarshalAs 属性修饰返回值会很有帮助。

此外，使用 System.Runtime.InteropServices.InAttribute 和 System.Runtime.InteropServices.OutAttribute 向封送器提供注释非常有效。代码示例对此进行了演示。

• 对象按创建顺序向下存储在栈中。
• 包含对象的对象也按声明顺序向下存储。
• 每个对象都有一个大小。该大小由其包含的对象决定（如果它不是基本类型的话）。

您可以通过两种方式获取对象的大小：sizeof 关键字和 System.Runtime.InteropServices.Marshal.SizeOf() 方法。推荐使用第二种方法。您知道为什么吗？尝试思考，然后回答。

[StructLayout(LayoutKind.Explicit)]
public struct CONSOLE_SCREEN_BUFFER_INFO
{
    [FieldOffset(18)]
    public COORD dwMaximumWindowSize;
    [FieldOffset(10)]
    public SMALL_RECT srWindow;
    [FieldOffset(8)]
    public ushort wAttributes;
    [FieldOffset(4)]
    public COORD dwCursorPosition;
    [FieldOffset(0)]
    public COORD dwSize;
}

如果将 LayoutKind 设置为 Auto，则无法使用该类型与非托管代码进行互操作。尽管如此，如果您省略了整个 StructLayoutAttribute。

[StructLayout(LayoutKind.Sequential)]
public struct CONSOLE_SCREEN_BUFFER_INFO
{
    public short dwSizeX;
    public short dwSizeY;
    public short dwCursorPositionX;
    public short dwCursorPositionY;
    public ushort wAttributes;
    public short srWindowLeft;
    public short srWindowTop;
    public short srWindowRight;
    public short srWindowBottom;
    public short dwMaximumWindowSizeX;
    public short dwMaximumWindowSizeY;
} 

听起来很奇怪，不是吗？您也可以将 LayoutKind 设置为 Explicit 并开始工作。

[StructLayout(LayoutKind.Sequential)]
public struct CONSOLE_SCREEN_BUFFER_INFO
{
    public COORD dwSize;
    public COORD dwCursorPosition;
    public ushort wAttributes;
    public SMALL_RECT srWindow;
    public COORD dwMaximumWindowSize;
}

[StructLayout(LayoutKind.Sequential)]
public struct COORD
{
    public short X;
    public short Y;
}

[StructLayout(LayoutKind.Sequential)]
public struct SMALL_RECT
{
    public short Left;
    public short Top;
    public short Right;
    public short Bottom;
}

unsafe static void Main()
{
    CONSOLE_SCREEN_BUFFER_INFO info
        = new CONSOLE_SCREEN_BUFFER_INFO();

    info.dwSize = new COORD();
    info.dwSize.X = 0xA1;
    info.dwSize.Y = 0xA2;

    info.dwCursorPosition = new COORD();
    info.dwCursorPosition.X = 0xB1;
    info.dwCursorPosition.Y = 0xB2;

    info.wAttributes = 0xFFFF;

    info.srWindow = new SMALL_RECT();
    info.srWindow.Left = 0xC1;
    info.srWindow.Top = 0xC2;
    info.srWindow.Right = 0xC3;
    info.srWindow.Bottom = 0xC4;

    info.dwMaximumWindowSize = new COORD();
    info.dwMaximumWindowSize.X = 0xD1;
    info.dwMaximumWindowSize.Y = 0xD2;

    uint memoryAddress =
        (uint)&info;

    Console.WriteLine(
        "Memory Address: 0x{0:X}",
        memoryAddress);

    Console.WriteLine("Press any key . . .");
    Console.ReadKey(true);

    // You can add a break point on the last line,
    // or you can use this function to break the code.
    System.Diagnostics.Debugger.Break();
}

此代码假定您已从项目属性的“生成”选项卡中启用了不安全代码。它还假定您通过按 F5 或从“调试”菜单中选择“开始调试”来运行代码。

BOOL FillConsoleOutputCharacter(
  HANDLE hConsoleOutput,
  TCHAR cCharacter,
  DWORD nLength,
  COORD dwWriteCoord,
  [out] LPDWORD lpNumberOfCharsWritten
);

• hConsoleOutput
  一个已打开的控制台输出设备的句柄，用于写入。
• cCharacter
  用于填充缓冲区部分的字符。
• nLength
  要写入的字符数。
• dwWriteCoord
  一个 COORD 结构，定义开始写入的位置（第一个单元格）。
• lpNumberOfCharsWritten：一个输出参数，确定写入的字符数。

[DllImport("Kernel32.dll")]
public static extern int FillConsoleOutputCharacter
    (IntPtr hConsoleOutput, char cCharacter, uint nLength,
    COORD dwWriteCoord, out uint lpNumberOfCharsWritten);

请注意，非托管数据类型 DWORD 和 LPDOWRD 已封送为 System.UInt32。有关非托管数据类型的更多信息，请参阅参考部分。

BOOL SetConsoleCursorPosition(
  HANDLE hConsoleOutput,
  COORD dwCursorPosition
); 

[DllImport("Kernel32.dll")]
public static extern int SetConsoleCursorPosition
    (IntPtr hConsoleOutput, COORD dwCursorPosition);

public const int STD_OUTPUT_HANDLE = -11;
public const char WHITE_SPACE = ' ';

[DllImport("Kernel32.dll")]
public static extern IntPtr GetStdHandle(int nStdHandle);

[DllImport("Kernel32.dll")]
public static extern int GetConsoleScreenBufferInfo
    (IntPtr hConsoleOutput,
    out CONSOLE_SCREEN_BUFFER_INFO lpConsoleScreenBufferInfo);

[DllImport("Kernel32.dll")]
public static extern int FillConsoleOutputCharacter
    (IntPtr hConsoleOutput, char cCharacter, uint nLength,
    COORD dwWriteCoord, out uint lpNumberOfCharsWritten);

[DllImport("Kernel32.dll")]
public static extern int SetConsoleCursorPosition
    (IntPtr hConsoleOutput, COORD dwCursorPosition);

[StructLayout(LayoutKind.Sequential)]
public struct CONSOLE_SCREEN_BUFFER_INFO
{
    public COORD dwSize;
    public COORD dwCursorPosition;
    public ushort wAttributes;
    public SMALL_RECT srWindow;
    public COORD dwMaximumWindowSize;
}

[StructLayout(LayoutKind.Sequential)]
public struct COORD
{
    public short X;
    public short Y;
}

[StructLayout(LayoutKind.Sequential)]
public struct SMALL_RECT
{
    public short Left;
    public short Top;
    public short Right;
    public short Bottom;
}

static void Main()
{
    Console.WriteLine("Writing some text to clear.");

    Console.WriteLine("Press any key to clear . . . ");
    Console.ReadKey(true);

    ClearConsoleScreen();
}

public static void ClearConsoleScreen()
{
    // Getting the console output device handle
    IntPtr handle = GetStdHandle(STD_OUTPUT_HANDLE);

    // Getting console screen buffer info
    CONSOLE_SCREEN_BUFFER_INFO info;
    GetConsoleScreenBufferInfo(handle, out info);

    // Discovering console screen buffer info
    Console.WriteLine("Console Buffer Info:");
    Console.WriteLine("--------------------");
    Console.WriteLine("Cursor Position:");
    Console.WriteLine("t{0}, {1}",
        info.dwCursorPosition.X, info.dwCursorPosition.Y);
    // Is this information right?
    Console.WriteLine("Maximum Window Size:");
    Console.WriteLine("t{0}, {1}",
        info.dwMaximumWindowSize.X,
        info.dwMaximumWindowSize.Y);
    // Is this information right?
    Console.WriteLine("Screen Buffer Size:");
    Console.WriteLine("t{0}, {1}",
        info.dwSize.X, info.dwSize.Y);
    Console.WriteLine("Screen Buffer Bounds:");
    Console.WriteLine("t{0}, {1}, {2}, {3}",
        info.srWindow.Left, info.srWindow.Top,
        info.srWindow.Right, info.srWindow.Bottom);
    Console.WriteLine("--------------------");

    // Location of which to begin clearing
    COORD location = new COORD();
    location.X = 0;
    location.Y = 0;
    // What about clearing starting from
    // the second line
    // location.Y = 1;

    // The number of written characters
    uint numChars;

    FillConsoleOutputCharacter(handle, WHITE_SPACE,
        (uint)(info.dwSize.X * info.dwSize.Y),
        location, out numChars);

    // The new cursor location
    COORD cursorLocation = new COORD();
    cursorLocation.X = 0;
    cursorLocation.Y = 0;

    SetConsoleCursorPosition(handle, cursorLocation);
}

static void Main()
{
    // Require the user to enter his password
    AuthenticateUser();
}

public static void AuthenticateUser()
{
    Console.WriteLine("Please enter your password:");
    Console.Write("> "); // Two characters right

    string input = Console.ReadLine();

    while (input != "MyPassword")
    {
        COORD location = new COORD();
        // The third character
        location.X = 2;
        // The second line
        location.Y = 1;
        ClearConsoleScreen(location);
        input = Console.ReadLine();
    }

    // User authenticated
    Console.WriteLine("Authenticated!");
}

public static void ClearConsoleScreen
    (COORD location)
{
    // Getting the console output device handle
    IntPtr handle = GetStdHandle(STD_OUTPUT_HANDLE);

    // Getting console screen buffer info
    CONSOLE_SCREEN_BUFFER_INFO info;
    GetConsoleScreenBufferInfo(handle, out info);

    // The number of written characters
    uint numChars;

    FillConsoleOutputCharacter(handle, WHITE_SPACE,
        (uint)(info.dwSize.X * info.dwSize.Y),
        location, out numChars);

    SetConsoleCursorPosition(handle, location);
}

如果您使用 .NET 2.0 或更高版本，您可以继续本节，否则，您可以跳过本节，因为 Clear() 方法是 .NET 2.0 的新增功能。

MSIL、CIL 和 IL 都指同一件事：中间语言。

MSCORLIB 代表 Microsoft Common Object Runtime Library。

对我来说，我更喜欢第一个工具，因为它更快、更简单，并且支持许多功能。

当然，您可以反射（逆向工程）一个程序集并从其中的代码中学习有用的技巧。

• Win32 数据类型
• GetStdHandle() 函数
• GetConsoleScreenBufferInfo() 函数
• FillConsoleOutputCharacter() 函数
• SetConsoleCursorPosition() 函数
• CONSOLE_SCREEN_BUFFER_INFO 结构
• COORD 结构
• SMALL_RECT 结构