.NET 命令列解析器 CommandLineParser 實戰：建立可擴充的檔案複製工具

專案需求

開發一個命令列工具 CopyFiles，支援以下參數：

• -s / --source：來源目錄（必填）
• -p / --pattern：檔案模式，如 *.csproj（必填）
• -t / --target：目標目錄（必填）
• -a / --all：是否遞迴子目錄（預設 true）
• -o / --overwrite：是否覆蓋同名檔案（預設 true）
• -v / --verbose：是否輸出詳細訊息（預設 true）
• --help：自動產生說明文件

範例呼叫：
CopyFiles -s "E:\Project" -p "*.cs" -t "E:\Backup" -a false -o true

套件安裝

dotnet add package CommandLineParser

選項類別設計

using CommandLine;
using CommandLine.Text;

namespace CopyFiles
{
    public class Options
    {
        [Option('s', "source", Required = true, HelpText = "來源目錄。")]
        public string SourcePath { get; set; }

        [Option('p', "pattern", Required = true, HelpText = "檔案模式（如 *.csproj）。")]
        public string SearchPattern { get; set; }

        [Option('t', "target", Required = true, HelpText = "目標目錄。")]
        public string TargetPath { get; set; }

        [Option('a', "all", Default = true, HelpText = "是否包含所有子目錄？")]
        public bool AllDirectories { get; set; }

        [Option('o', "overwrite", Default = true, HelpText = "是否覆蓋現有檔案？")]
        public bool Overwrite { get; set; }

        [Option('v', "verbose", Default = true, HelpText = "是否輸出詳細訊息？")]
        public bool Verbose { get; set; }

        [HelpOption]
        public string GetUsage() => HelpText.AutoBuild(this);

        /// 

        /// 依 Verbose 設定決定是否輸出
        /// 
        public void WriteLine(string format, params object[] args)
        {
            if (Verbose) Console.WriteLine(string.Format(format, args));
        }
    }
}

主程式與檔案複製邏輯

using CommandLine;
using System;
using System.IO;

namespace CopyFiles
{
    class Program
    {
        static void Main(string[] args)
        {
            var options = new Options();
            if (Parser.Default.ParseArguments(args, options))
            {
                FileUtil.Copy(
                    options.SourcePath,
                    options.SearchPattern,
                    options.TargetPath,
                    onCopy: (src, dest) => options.WriteLine("複製：{0} → {1}", src, dest),
                    onError: err => 
                    {
                        options.WriteLine("錯誤：{0}", err.Exception.Message);
                        err.Handled = true; // 繼續處理下一個檔案
                    },
                    options.AllDirectories,
                    options.Overwrite
                );
            }
        }
    }

    /// 

    /// 簡易檔案複製工具（示範用，生產環境建議用 Robocopy 或更健壯的庫）
    /// 
    public static class FileUtil
    {
        public static void Copy(string sourceDir, string pattern, string targetDir,
            Action onCopy, Action onError,
            bool recursive, bool overwrite)
        {
            var searchOpt = recursive ? SearchOption.AllDirectories : SearchOption.TopDirectoryOnly;
            foreach (var file in Directory.GetFiles(sourceDir, pattern, searchOpt))
            {
                try
                {
                    string relPath = file.Substring(sourceDir.Length).TrimStart('\\', '/');
                    string destFile = Path.Combine(targetDir, relPath);
                    Directory.CreateDirectory(Path.GetDirectoryName(destFile));
                    File.Copy(file, destFile, overwrite);
                    onCopy?.Invoke(file, destFile);
                }
                catch (Exception ex)
                {
                    onError?.Invoke(new ErrorInfo { Exception = ex, Handled = false });
                }
            }
        }

        public class ErrorInfo { public Exception Exception { get; set; } public bool Handled { get; set; } }
    }
}

進階技巧與常見坑

1. 多值參數（陣列/清單）

[Option('e', "exclude", Separator = ',', HelpText = "排除模式，以逗號分隔")]
public IEnumerable ExcludePatterns { get; set; }

2. 子命令（Verb）支援

[Verb("copy", HelpText = "複製檔案")]
public class CopyOptions { ... }

[Verb("sync", HelpText = "同步目錄")]
public class SyncOptions { ... }

// Main
Parser.Default.ParseArguments(args)
    .MapResult(
        (CopyOptions o) => RunCopy(o),
        (SyncOptions o) => RunSync(o),
        errs => 1
    );

3. 自動生成的 --help 輸出範例

CopyFiles 1.0.0
-s, --source      來源目錄。
-p, --pattern     檔案模式（如 *.csproj）。
-t, --target      目標目錄。
-a, --all         是否包含所有子目錄？
-o, --overwrite   是否覆蓋現有檔案？
-v, --verbose     是否輸出詳細訊息？
--help            顯示此說明。

總結

CommandLineParser 以屬性標記定義選項、自動對應型別、內建 --help 產生、支援子命令與複雜驗證，是 .NET 命令列工具開發的首選庫。本文示範的 CopyFiles 專案可直接擴充為生產級備份/同步工具。