教程:结合使用多项 C# 技术生成胸牌标签

聚会需要按姓名顺序排列的徽章标签。 每位参会者会索取一个或多个标签,每个标签上都包含有关参会者角色的文字信息。 在本教程中,你将结合一些小的 C# 技巧来生成标签,而无需单独的格式化字符串集合。

本教程面向了解基本 C# 方法、循环和集合的开发人员。 选择短操作所属的位置,将辅助程序的依赖关系明确表示出来,并决定程序何时生成结果。 有关这些选择背后的理由,请参阅构建软件。

Prerequisites

首先为每位参会者生成一个标签

  1. 创建一个名为 BadgeLabels 的文件夹,并在其中创建一个名为 Program.cs 的文件。

  2. 将以下部分中的完整源复制到 Program.cs 中。 对每个步骤和试验使用此相同的文件:

    #define BADGE_SORT
    #define BADGE_COPIES
    #define BADGE_FORMAT
    #define BADGE_COUNT
    // #define BADGE_DIAGNOSTICS
    // #define BADGE_REPEAT
    // #define BADGE_SNAPSHOT
    
    Attendee[] attendees =
    [
        new("Ben", "Host", 1),
        new("Ada", "Guest", 2)
    ];
    
    #if BADGE_SORT
    #if BADGE_DIAGNOSTICS
    Console.WriteLine("Before query definition.");
    #endif
    var orderedAttendees = attendees.OrderBy(
    #if BADGE_DIAGNOSTICS
        attendee =>
        {
            Console.WriteLine($"Sort key: {attendee.Name}");
            return attendee.Name;
        }, StringComparer.Ordinal);
    #else
        attendee => attendee.Name, StringComparer.Ordinal);
    #endif
    #if BADGE_DIAGNOSTICS
    Console.WriteLine("After query definition.");
    #endif
    #else
    var orderedAttendees = attendees;
    #endif
    
    #if BADGE_SNAPSHOT
    var attendeesToPrint = orderedAttendees.ToList();
    #else
    var attendeesToPrint = orderedAttendees;
    #endif
    
    int passes = 1;
    #if BADGE_REPEAT
    passes = 2;
    #endif
    
    for (int pass = 0; pass < passes; pass++)
    {
    #if BADGE_COUNT
        int expected = attendees.Sum(attendee => attendee.Copies);
        int printed = 0;
    #endif
    
        foreach (Attendee attendee in attendeesToPrint)
        {
    #if BADGE_COPIES
            var labels = CreateLabels(attendee);
    #if BADGE_DIAGNOSTICS
            Console.WriteLine($"Sequence created: {attendee.Name}");
    #endif
            foreach (string label in labels)
            {
                Console.WriteLine(label);
    #if BADGE_COUNT
                printed++;
    #endif
            }
    #else
            Console.WriteLine($"{attendee.Name} | {attendee.Role}");
    #endif
        }
    
    #if BADGE_COUNT
        if (printed != expected)
        {
            throw new InvalidOperationException("Label count doesn't match the request.");
        }
    
        Console.WriteLine($"Printed {printed} of {expected} requested labels.");
    #endif
    }
    
    #if BADGE_COPIES
    static IEnumerable<string> CreateLabels(Attendee attendee)
    {
    #if BADGE_DIAGNOSTICS
        Console.WriteLine($"Iterator started: {attendee.Name}");
    #endif
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(attendee.Copies);
    
    #if BADGE_FORMAT
        string message = attendee.Role switch
        {
            "Guest" => "Welcome!",
            "Host" => "Ask me for help",
            _ => throw new ArgumentException(
                $"Unsupported role: {attendee.Role}.", nameof(attendee))
        };
    #endif
    
        for (int copy = 1; copy <= attendee.Copies; copy++)
        {
    #if BADGE_FORMAT
            yield return FormatLabel(
                attendee.Name, attendee.Role, message, copy, attendee.Copies);
    #else
            yield return $"{attendee.Name} | {attendee.Role} [{copy}/{attendee.Copies}]";
    #endif
        }
    
    #if BADGE_FORMAT
        static string FormatLabel(
            string name, string role, string message, int copy, int total) =>
            $"{name} | {role} | {message} [{copy}/{total}]";
    #endif
    }
    #endif
    
    record Attendee(string Name, string Role, int Copies);
    
  3. 在文件的顶部,注释掉四个启用的 #define 行。 也请将这三行实验代码保持为注释状态。

  4. 在该文件夹中,运行 基于文件的应用:

    dotnet run --file Program.cs
    

程序写入:

Ben | Host
Ada | Guest

该文件包含每个阶段。 从现在起,仅更改顶部的 #define 行,而不是方法主体或声明。 #if指令仅在其符号已定义时才包含代码;#else分支提供替代项。 请参阅 条件编译。

在每个步骤中取消注释一个额外的阶段行,并保持前面的阶段行处于启用状态:

阶段 活动阶段符号
每个与会者一个标签 无
对与会者进行排序 BADGE_SORT
创建副本 BADGE_SORT、BADGE_COPIES
格式化消息 BADGE_SORT、BADGE_COPIES、BADGE_FORMAT
验证计数 BADGE_SORT、BADGE_COPIES、BADGE_FORMAT、BADGE_COUNT

下载的源代码启用了全部四个阶段的符号,因此它默认运行最终程序。 其他三个符号控制可选试验,并在正常进度期间保持关闭。 这些符号使用 BADGE_ 前缀来避免 SDK 定义的符号,例如 TRACE。

以下摘录突出显示文件中已有的代码。 不要将它们复制到完整程序中。

Attendee[] attendees =
[
    new("Ben", "Host", 1),
    new("Ada", "Guest", 2)
];

Attendee 声明定义了 记录,一种类型,用于对相关数据进行分组并提供基于值的相等性。 每个与会者都有一个 Name、一个 Role和所需数量的 Copies。 记录适合此小型数据模型,因为该计划在操作之间传递与会者数据而不更改它。 有关此类型的详细信息,请参阅 记录。

固定输入使用了数组和集合表达式。 在每个 new(...) 调用中,C# 从数组元素类型推断 Attendee ;请参阅 Target 类型 new。 顶级语句 使你无需编写 Main 方法即可运行该示例。

foreach循环读取每个与会者,内插字符串将其值插入到输出中。 循环当前忽略 Copies。

在开发程序时保留此小输入:Ben 请求一个副本,Ada 请求两个副本。 仅支持 Guest 和 Host 这两种角色,并且复制计数必须为正数。

使用 lambda 进行排序

若要按姓名顺序放置与会者,请去掉 #define BADGE_SORT 的注释。 将其他符号保留为注释状态。排序分支定义此查询:

var orderedAttendees = attendees.OrderBy(
#if BADGE_DIAGNOSTICS
    attendee =>
    {
        Console.WriteLine($"Sort key: {attendee.Name}");
        return attendee.Name;
    }, StringComparer.Ordinal);
#else
    attendee => attendee.Name, StringComparer.Ordinal);
#endif

诊断关闭后 #else ,分支会提供短 lambda。 该循环打印排序后的与会者:

    foreach (Attendee attendee in attendeesToPrint)
    {
#if BADGE_COPIES
        var labels = CreateLabels(attendee);
#if BADGE_DIAGNOSTICS
        Console.WriteLine($"Sequence created: {attendee.Name}");
#endif
        foreach (string label in labels)
        {
            Console.WriteLine(label);
#if BADGE_COUNT
            printed++;
#endif
        }
#else
        Console.WriteLine($"{attendee.Name} | {attendee.Role}");
#endif
    }

运行相同的命令。 输出现在首先放置 Ada:

Ada | Guest
Ben | Host

attendee => attendee.Name 是 lambda 表达式,它是在代码需要某种行为时提供的未命名函数。 在这里,lambda 选择用于排序的名称。 lambda 直接在 调用中保持OrderBy,因为它很短,其用途很明显。 可以将所选内容提取到命名的帮助程序方法中,但方法名称不会更好地解释此单属性选择。 请参阅 Lambda 表达式。

OrderBy是语言集成查询(LINQ)的一部分,它是一组 C# 功能和.NET API,用于查询数据。 请参阅 LINQ 查询。

此示例使用方法语法,它会直接调用 LINQ 方法。 相比之下, 查询语法 使用 C# 子句,例如 from, orderby和 select:

var orderedAttendees =
    from attendee in attendees
    orderby attendee.Name
    select attendee;

编译器将查询语法转换为方法调用。 查询语法可以使具有多个子句的查询更易于读取;方法语法使这一排序写法更简洁,并允许将比较器传递给 OrderBy。 查询语法示例使用默认字符串比较器,因此它不能保证跨区域设置的顺序相同。 保留此程序的方法语法版本。 请参阅 LINQ 方法和查询语法。

为了使输出独立于计算机的区域性,示例使用 Ordinal 进行名称比较。 对于此处的短名称,该顺序按字母顺序排列。 请参阅 使用 LINQ 对数据进行排序。

var 声明允许编译器推断查询变量的类型。 该 orderedAttendees 变量描述查询,而不是已完成的排序集合。 对枚举一个序列,意味着逐个读取其元素。 当 foreach 首次请求元素时,OrderBy 读取并排序所有与会者。

观察执行顺序

延迟执行 意味着代码枚举序列而不是代码定义查询时开始工作。 请参阅 “运行查询”。 使用诊断输出查看差异:

  1. 仅在阶段符号中保持 BADGE_SORT 为启用状态。

  2. 取消注释 #define BADGE_DIAGNOSTICS 在同一文件的顶部。 诊断分支用消息将查询定义括起来,并使用输出每个排序键的 lambda:

    #if BADGE_SORT
    #if BADGE_DIAGNOSTICS
    Console.WriteLine("Before query definition.");
    #endif
    var orderedAttendees = attendees.OrderBy(
    #if BADGE_DIAGNOSTICS
        attendee =>
        {
            Console.WriteLine($"Sort key: {attendee.Name}");
            return attendee.Name;
        }, StringComparer.Ordinal);
    #else
        attendee => attendee.Name, StringComparer.Ordinal);
    #endif
    #if BADGE_DIAGNOSTICS
    Console.WriteLine("After query definition.");
    #endif
    #else
    var orderedAttendees = attendees;
    #endif
    
  3. 再次运行 dotnet run --file Program.cs 。 在读取输出之前,请预测 Sort key: 出现在 After query definition. 之前还是之后。

输出为:

Before query definition.
After query definition.
Sort key: Ben
Sort key: Ada
Ada | Guest
Ben | Host

两个查询定义消息之间没有出现排序键。 仅当 foreach 请求第一个结果时,lambda 才会运行。 两条键消息都显示在第一个标签之前,因为 OrderBy 需要先获取所有键,才能确定哪位参会者排在首位。 键遵循输入顺序,Ben 然后 Ada;结果遵循排序顺序,Ada,然后 Ben。

诊断 lambda 既需要消息,也需要返回的键,因此它使用带大括号的 return 和 ,而不是原来的单表达式正文。

启用诊断后,请尝试同一文件中的两个试验开关。 无需对循环或查询进行更改:

  1. 取消注释 #define BADGE_REPEAT 并再次运行:

    Before query definition.
    After query definition.
    Sort key: Ben
    Sort key: Ada
    Ada | Guest
    Ben | Host
    Sort key: Ben
    Sort key: Ada
    Ada | Guest
    Ben | Host
    

    第二趟再次进行排序。 查询变量不缓存结果。

  2. 保持 BADGE_REPEAT 启用、取消注释 #define BADGE_SNAPSHOT并再次运行:

    Before query definition.
    After query definition.
    Sort key: Ben
    Sort key: Ada
    Ada | Guest
    Ben | Host
    Ada | Guest
    Ben | Host
    

    现在,两条键消息仅在 ToList 期间出现一次,并且在任意一轮遍历输出标签之前。 两轮遍历都读取存储的参会者。

这些开关选择要枚举的序列和遍数:

#if BADGE_SNAPSHOT
var attendeesToPrint = orderedAttendees.ToList();
#else
var attendeesToPrint = orderedAttendees;
#endif

int passes = 1;
#if BADGE_REPEAT
passes = 2;
#endif

即时执行 意味着操作会立即运行,而不是等待以后的枚举。 ToList 立即执行查询,并将其结果存储在列表中。 两轮遍历现在读取存储的参会者,而无需再次运行排序。 相比之下,定义 OrderBy 查询仍会将排序延后:它仅在枚举开始时读取和缓冲所有输入。 缓冲并不意味着查询会在定义时执行。 如果需要重复使用结果而不重新计算结果,请使用快照;如果希望每个枚举读取当前输入,请保留延迟查询。 请参阅 使用缓存结果编写查询。

在继续之前,请再次将 BADGE_DIAGNOSTICS、BADGE_REPEAT 和 BADGE_SNAPSHOT 注释掉。 保持 BADGE_SORT 启用状态。 运行应用以确认只显示两个已排序的标签。

使用迭代器生成所请求的副本

要为每位参会者生成所需数量的标签,请取消注释 #define BADGE_COPIES 和 BADGE_SORT。 循环现在选择 BADGE_COPIES 前面显示的分支,并调用文件中已有的迭代器:

#if BADGE_COPIES
static IEnumerable<string> CreateLabels(Attendee attendee)
{
#if BADGE_DIAGNOSTICS
    Console.WriteLine($"Iterator started: {attendee.Name}");
#endif
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(attendee.Copies);

#if BADGE_FORMAT
    string message = attendee.Role switch
    {
        "Guest" => "Welcome!",
        "Host" => "Ask me for help",
        _ => throw new ArgumentException(
            $"Unsupported role: {attendee.Role}.", nameof(attendee))
    };
#endif

    for (int copy = 1; copy <= attendee.Copies; copy++)
    {
#if BADGE_FORMAT
        yield return FormatLabel(
            attendee.Name, attendee.Role, message, copy, attendee.Copies);
#else
        yield return $"{attendee.Name} | {attendee.Role} [{copy}/{attendee.Copies}]";
#endif
    }

#if BADGE_FORMAT
    static string FormatLabel(
        string name, string role, string message, int copy, int total) =>
        $"{name} | {role} | {message} [{copy}/{total}]";
#endif
}
#endif

再次运行应用:

Ada | Guest [1/2]
Ada | Guest [2/2]
Ben | Host [1/1]

CreateLabels 是 迭代器,一个一次生成序列元素的函数。 其 IEnumerable<T> 返回类型(写为 IEnumerable<string>)表示字符串序列。 每次 yield return 都会向内层 foreach 循环提供一个标签,内层循环会在输出标签后,再请求下一个标签。 请参阅 迭代器。

for循环从 1 计数到 attendee.Copies。 一位参会者生成的字符串数量与 Copies 请求的数量相同。 集合也可以,但调用方只需要每个标签一次。 迭代器可避免维护单独的标签集合,并将副本编号循环整合在一起。 外部和内部 foreach 循环将与会者顺序与标签生产分开;调用方仍负责打印。

调用 CreateLabels(attendee) 不会运行其主体。 与 LINQ 查询一样,迭代器使用延迟执行。 内层 foreach 启动了该工作,包括副本数量为正检查。 新的枚举过程会再次遍历该迭代器。 OrderBy 会先读取全部参会者数据并进行排序,再输出第一条结果;与之不同,此迭代器可以先提供一个标签,而不创建其余标签。

若要观察迭代器按什么顺序执行,请再次取消注释 #define BADGE_DIAGNOSTICS。 保持 BADGE_REPEAT 和 BADGE_SNAPSHOT 关闭。 诊断现在同时显示排序和迭代器:

Before query definition.
After query definition.
Sort key: Ben
Sort key: Ada
Sequence created: Ada
Iterator started: Ada
Ada | Guest [1/2]
Ada | Guest [2/2]
Sequence created: Ben
Iterator started: Ben
Ben | Host [1/1]

对于每个与会者,序列创建的消息显示在迭代器启动消息和标签之前。 创建序列不会进入迭代器主体;请求其第一个元素会执行该操作。 在继续之前再次注释掉 BADGE_DIAGNOSTICS 。

在后续阶段,相同的实验对照条件仍然可用。 BADGE_REPEAT 枚举与会者两次,并再次创建每个与会者的标签序列。 BADGE_SNAPSHOT 只缓存已排序的与会者,而不是标记字符串,因此会阻止再次排序,但不会阻止迭代器在每次遍历时再次运行。

检查 ThrowIfNegativeOrZero 会报告无效输入,而不是静默地不生成任何标签。 异常会报告一种中断正常执行的失败;请参阅创建并引发异常。 在这里,无效的复制计数会停止程序,而不是以无提示方式跳过该与会者。

计算消息并命名格式步骤

每个角色都需要不同的消息。 取消注释 #define BADGE_FORMAT,并保持 BADGE_SORT 和 BADGE_COPIES 启用。 同一迭代器现在包括消息计算:

#if BADGE_FORMAT
    string message = attendee.Role switch
    {
        "Guest" => "Welcome!",
        "Host" => "Ask me for help",
        _ => throw new ArgumentException(
            $"Unsupported role: {attendee.Role}.", nameof(attendee))
    };
#endif

它还选择 yield return FormatLabel(...) 分支并包括此本地辅助函数:

#if BADGE_FORMAT
    static string FormatLabel(
        string name, string role, string message, int copy, int total) =>
        $"{name} | {role} | {message} [{copy}/{total}]";
#endif

再次运行应用:

Ada | Guest | Welcome! [1/2]
Ada | Guest | Welcome! [2/2]
Ben | Host | Ask me for help [1/1]

switch 表达式会在副本循环开始之前,为每位参会者计算一次消息。 这里适合使用表达式,因为每个角色都会选择一个值赋给 message。 if else /链或switch语句可以正常工作,但会在每个分支中重复赋值。

模式匹配 针对指定的模式测试表达式。 这里,attendee.Role是输入表达式,而常量模式"Guest"和"Host"会测试其计算值以选择匹配的消息。 弃元模式_ 用于匹配所有其他角色并引发异常,因此不受支持的角色不会收到误导性的默认消息。 请参阅 模式匹配。

nameof 运算符向异常提供参数名称attendee。 与硬编码字符串不同,如果使用重构工具重命名参数,该名称仍然正确。

FormatLabel 是 一个局部函数,它是在另一个函数内声明的命名函数。 由于只有 CreateLabels 需要格式化操作,因此将其置于 CreateLabels 内可以将帮助程序限定在使用它的操作中。 类上的私有成员方法将使帮助程序可供该类的其他成员使用。 如果多个操作需要相同的格式设置操作,请选择更广泛的范围。 请参阅 本地函数。

名称 FormatLabel 让你能够理清复制循环,而无需读取格式详细信息。 将内插字符串直接保留在 yield return 中也会正常工作,就像在上一步中一样。 现在标签包含特定于角色的消息,该名称将变得更加有用。 帮助程序的 => 表达式主体会返回一个格式化后的字符串。

所有格式输入都通过参数传入。 非静态本地函数可以从其周围范围 捕获或使用变量。 static 修饰符会阻止该捕获,因此其依赖项会保持显式。 请参阅 参数和捕获的状态。

由于 CreateLabels 仍然是迭代器,因此角色检查仅在枚举启动时运行。 对于此受控输入,这些检查应该放在标签生成中。 该计划不承诺在打印任何标签之前验证所有与会者。

核对总数并运行完整的程序

若要将实际标签生产与请求的计数进行比较,请取消注释 #define BADGE_COUNT。 所有四个阶段符号现已启用。 将三个实验符号保留为注释状态,以用于正常的最终输出。

计数设置在与会者循环之前运行:

#if BADGE_COUNT
    int expected = attendees.Sum(attendee => attendee.Copies);
    int printed = 0;
#endif

Sum 使用即时执行对输入数组中的副本计数进行求和。 与 OrderBy 不同,它返回一个数字,而不是一个可在稍后枚举的序列。 其 lambda,attendee => attendee.Copies以内联方式选择复制计数。 与名称选择一样,单独的帮助程序方法不会阐明此简短的表达式。 使用带累加器的循环也可以实现;Sum 直接表明你想要获得总计。 请参阅 常见的 LINQ 方法。

标签循环中的 printed++ increment 仅在循环收到标签时,才会增加计数器的值。 在该循环之后,该if语句将该计数与请求的总和进行比较,并在这些计数不同时引发异常:

#if BADGE_COUNT
    if (printed != expected)
    {
        throw new InvalidOperationException("Label count doesn't match the request.");
    }

    Console.WriteLine($"Printed {printed} of {expected} requested labels.");
#endif

你已经得到最开始复制的完整程序的默认配置。 无需更改任何方法或声明:

#define BADGE_SORT
#define BADGE_COPIES
#define BADGE_FORMAT
#define BADGE_COUNT
// #define BADGE_DIAGNOSTICS
// #define BADGE_REPEAT
// #define BADGE_SNAPSHOT

使用 dotnet run --file Program.cs 运行它。 输出为:

Ada | Guest | Welcome! [1/2]
Ada | Guest | Welcome! [2/2]
Ben | Host | Ask me for help [1/1]
Printed 3 of 3 requested labels.

输入数组已在内存中。 Sum 立即读取它,OrderBy 在与会者循环开始时对其进行排序,并且 CreateLabels 随着内部循环推进生成字符串。 程序永远不会生成单独的标签集合。 有关更广泛的查询指南,请参阅 LINQ 和集合。

要在最终程序中重新访问诊断信息,请仅启用实验符号中的 BADGE_DIAGNOSTICS。 输出为:

Before query definition.
After query definition.
Sort key: Ben
Sort key: Ada
Sequence created: Ada
Iterator started: Ada
Ada | Guest | Welcome! [1/2]
Ada | Guest | Welcome! [2/2]
Sequence created: Ben
Iterator started: Ben
Ben | Host | Ask me for help [1/1]
Printed 3 of 3 requested labels.

如果还启用 BADGE_REPEAT,则每次遍历都会检查并报告各自的计数。 启用 BADGE_SNAPSHOT 后,排序键仅显示一次,但迭代器消息、标签和计数报告仍会在每轮遍历时显示。 将实验符号注释掉以还原正常的最终输出。

Summary

每个技术都为同一任务的不同部分提供服务:

  • Lambda 和 LINQ 以内联方式选择名称并获取副本计数,以用于排序和总计。
  • 迭代器 表示自定义的一对多生成,并将标签消耗交给调用方处理。
  • switch 表达式计算特定于角色的值,并明确指出不受支持的角色。
  • 本地函数 为格式化步骤命名、限制其范围并声明其输入。

当这些表单的范围、依赖项和执行顺序适用于该操作时,请选择这些表单。 直接循环、共享方法或已完成的集合可能更适合其他调用方。