练习 - 使用 GitHub Copilot 工具分析和记录代码

  • 20 分钟

GitHub Copilot 可通过生成解释和文档来帮助你了解和记录代码库。 在本练习中，你将使用 GitHub Copilot 分析和记录图书馆应用程序。 你还将为图书馆应用程序创建一个 GitHub 存储库，并使用 GitHub Copilot 为该存储库生成一个 README 文件。

本练习包括以下任务：

  • 使用 GitHub Copilot 解释图书馆应用程序代码库。
  • 使用 Visual Studio Code 为图书馆应用程序创建一个 GitHub 存储库。
  • 使用 GitHub Copilot 扩展分析解决方案，并为存储库创建一个 README.md 文件。

检查图书馆应用程序代码库

在创建代码存储库和 README 文件之前，应花一些时间检查代码库。 在记录项目之前，请务必了解应用的体系结构和关键功能。 还应运行应用程序，确保它按预期运行。

使用 GitHub Copilot 解释图书馆应用程序代码库

GitHub Copilot 可以在解决方案和功能层面生成解释，帮助你了解不熟悉的代码库。

请使用以下步骤完成本练习的这一部分：

  1. 确保在 Visual Studio Code 中打开 AccelerateDevGitHubCopilot 解决方案。

  2. 打开“聊天”视图，然后输入一个提示，以使用 GitHub Copilot 的 @workspace 参与者生成项目说明。

    例如，在“聊天”视图中输入以下提示：

    @workspace Describe this project

  3. 花几分钟时间查看答复。

    你应会看到类似于以下说明的答复：

    This project is a library management system implemented in C#. It consists of three main components:

1. **Library.ApplicationCore**: This is the core application library containing the main business logic, entities, enums, and interfaces. It includes:

    - Entities such as Book, Patron, Loan, etc.
    - Enums like MembershipRenewalStatus, LoanReturnStatus, and LoanExtensionStatus.
    - Services like LoanService and PatronService.
    - Interfaces like ILoanRepository, IPatronRepository, ILoanService, and IPatronService.

2. **Library.Console**: This is a console application that interacts with the user. It includes:

    - The main entry point in Program.cs.
    - Configuration settings in appSettings.json.
    - Console interaction logic in ConsoleApp.cs.

3. **Library.Infrastructure**: This library handles data persistence. It includes:

    - JSON-based repositories like JsonPatronRepository and JsonLoanRepository.
    - Data loading and saving logic in JsonData.

Additionally, there are unit tests located in the UnitTests directory, which test the functionality of the core services using the NSubstitute mocking framework and xUnit.

The project uses .NET 8.0 and is configured to build and test using GitHub Actions as defined in the build-test.yml file. The solution file is AccelerateDevGitHubCopilot.sln, which includes all the projects and their configurations.

  4. 使用“解决方案资源管理器”视图展开项目文件夹。

  5. 找到并打开 ConsoleApp.cs 文件。

    ConsoleApp.cs 文件位于 src/Library.Console 文件夹中。

  6. 在“聊天”视图中输入一个提示，以生成 ConsoleApp 类的说明。

    例如，在“聊天”视图中输入以下提示：

    @workspace #editor Describe the ConsoleApp class

  7. 花几分钟时间查看答复。

    你应会看到类似于以下说明的答复：

    The `ConsoleApp` class in `ConsoleApp.cs` is responsible for managing the console-based user interface of the library management system. It handles user interactions, processes user inputs, and coordinates actions with the underlying services and repositories.

### Fields
- `_currentState`: Tracks the current state of the console application.
- `matchingPatrons`: A list of patrons that match a search query.
- `selectedPatronDetails`: Holds details of the currently selected patron.
- `selectedLoanDetails`: Holds details of the currently selected loan.
- `_patronRepository`: An instance of `IPatronRepository` for accessing patron data.
- `_loanRepository`: An instance of `ILoanRepository` for accessing loan data.
- `_loanService`: An instance of `ILoanService` for performing loan-related operations.
- `_patronService`: An instance of `IPatronService` for performing patron-related operations.

### Constructor
- `ConsoleApp(ILoanService loanService, IPatronService patronService, IPatronRepository patronRepository, ILoanRepository loanRepository)`: Initializes the `ConsoleApp` with the provided services and repositories.

### Methods
- `Run()`: The main entry point for running the console application.
- `PatronSearch()`: Handles the logic for searching patrons.
- `ReadPatronName()`: Reads the patron's name from the console input.
- `PrintPatronsList(List<Patron> matchingPatrons)`: Prints a list of matching patrons to the console.
- `PatronSearchResults()`: Handles the logic for displaying and selecting from the search results.
- `ReadInputOptions(CommonActions options, out int optionNumber)`: Reads input options from the console.
- `WriteInputOptions(CommonActions options)`: Writes the available input options to the console.
- `PatronDetails()`: Displays details of the selected patron.
- `LoanDetails()`: Displays details of the selected loan and handles actions like extending or returning the loan.

The class uses a state machine approach to manage different states of the console application, such as searching for patrons, displaying search results, showing patron details, and handling loan details.

  8. 打开 Program.cs 文件。

  9. 在“聊天”视图中输入一个提示，以生成 Program.cs 文件的说明。

    例如，在“聊天”视图中输入以下提示：

    @workspace #editor Describe the Program.cs file

  10. 花几分钟时间查看答复。

    你应会看到类似于以下说明的答复：

    The `Program.cs` file is the entry point for the console application. It sets up the dependency injection container, configures services, and starts the `ConsoleApp`.

1. **Dependency Injection Setup**:
    - Creates a `ServiceCollection` to register services.
    - Builds a configuration object from the `appSettings.json` file.
    - Registers various services and repositories with different lifetimes (singleton, scoped).

2. **Service Registration**:
    - Registers the repositories: JsonPatronRepository and JsonLoanRepository.
    - Registers the services: LoanService and PatronService.
    - Registers the JsonData class as a singleton.
    - Registers the ConsoleApp class as a singleton.

3. **Service Provider**:
    - Builds the service provider from the registered services.
    - Retrieves the `ConsoleApp` service and runs it asynchronously.

This setup ensures that all dependencies are properly injected and configured before the application starts running.

  11. 展开 Library.Infrastructure 项目文件夹。

  12. 将以下文件添加到聊天上下文：JsonData.cs、JsonLoanRepository.cs 和 JsonPatronRepository.cs 文件。

    使用“附加上下文”按钮将文件添加到聊天上下文。 还可以使用拖放操作将文件添加到聊天上下文。

  13. 在“聊天”视图中输入一个提示，以生成数据访问类的说明。

    例如，在“聊天”视图中输入以下提示：

    @workspace /explain Explain how the data access classes work

  14. 花几分钟时间查看答复。

    你应会看到类似于以下说明的答复：

    The `JsonData` class in `JsonData.cs` is responsible for managing the loading and saving of data from JSON files. It handles various entities such as `Author`, `Book`, `BookItem`, Patron`, and `Loan`. The class uses the `IConfiguration` interface to read file paths from the configuration settings, ensuring that the correct JSON files are loaded.

The constructor of the `JsonData` class initializes the file paths for each entity by reading from the configuration section "JsonPaths". If the paths are not specified in the configuration, it defaults to specific paths within a "Json" directory.

The `EnsureDataLoaded` method checks if the data is already loaded and, if not, calls the `LoadData` method to load the data from the JSON files. The `LoadData` method reads the JSON files and deserializes them into the respective lists of entities.

The `SaveLoans` and `SavePatrons` methods handle saving the loan and patron data back to the JSON files. These methods ensure that only a subset of properties is saved, maintaining data integrity and consistency.

The class also provides methods to populate entities with related data. For example, `GetPopulatedPatrons` and `GetPopulatedPatron` methods populate patron entities with their associated loans. Similarly, `GetPopulatedLoan` and `GetPopulatedBookItem` methods populate loan and book item entities with their related data.

The `LoadJson` and `SaveJson` methods are utility methods for reading from and writing to JSON files. They use the `JsonSerializer` class to handle the serialization and deserialization processes.

Overall, the `JsonData` class serves as a central point for managing the persistence of data in JSON format, ensuring that the application can load, save, and manipulate data efficiently.

  15. 花几分钟时间检查用于模拟图书馆记录的 JSON 数据文件。

    JSON 数据文件位于 src/Library.Console/Json 文件夹中。

    数据文件使用 ID 属性来链接实体。 例如，Loan 对象有一个 PatronId 属性，可链接到一个具有相同 ID 的 Patron 对象。 JSON 文件包含作者、书籍、书籍项、借阅者和借阅记录的数据。

    注意

    请注意，出于本指导项目的目的，作者姓名、书籍标题和借阅者姓名已经过匿名化处理。

生成并运行应用程序

运行应用程序将帮助你了解用户界面、应用程序的关键功能以及应用组件的交互方式。

请使用以下步骤完成本练习的这一部分：

  1. 确保已打开“解决方案资源管理器”视图。

    “解决方案资源管理器”视图与“资源管理器”视图不同。 “解决方案资源管理器”视图使用项目和解决方案文件作为“目录”节点来显示解决方案的结构。

  2. 若要运行该应用程序，请右键单击“Library.Console”，选择“调试”，然后选择“启动新实例”。

    如果未显示“调试”和“启动新实例”选项，请确保使用的是“解决方案资源管理器”视图，而不是“资源管理器”视图。

    以下步骤将引导你完成一个简单的用例。

  3. 当系统提示你输入借阅者姓名时，请键入 1，然后按 Enter。

    你应会看到与搜索查询匹配的借阅者列表。

    注意

    该应用程序使用区分大小写的搜索过程。

  4. 在“输入选项”提示处键入 2，然后按 Enter。

    输入 2 会选择列表中的第二位借阅者。

    你应会看到借阅者的姓名和会员状态，以及书籍的借阅详细信息。

  5. 在“输入选项”提示处键入 1，然后按 Enter。

    输入 1 会选择列表中的第一本书。

    你应会看到列出的书籍详细信息，包括到期日期和归还状态。

  6. 在“输入选项”提示处键入 r，然后按 Enter。

    输入 r 将归还书籍。

  7. 确认是否显示“书籍已成功归还。”的消息。

    “书籍已成功归还。”的消息之后应显示书籍详细信息。 已归还的书籍会标记为 Returned: True。

  8. 若要开始新的搜索，请键入 s，然后按 Enter。

  9. 当系统提示你输入借阅者姓名时，请键入 1，然后按 Enter。

  10. 在“输入选项”提示处键入 2，然后按 Enter。

  11. 确认第一本书籍的借阅记录是否标记为 Returned: True。

  12. 在“输入选项”提示处键入 q，然后按 Enter。

  13. 停止调试会话。

为代码创建 GitHub 存储库

为代码创建 GitHub 存储库，可以方便你与他人分享工作成果并协作处理项目。

注意

使用自己的 GitHub 帐户为图书馆应用程序创建一个专用 GitHub 存储库。

请使用以下步骤完成本练习的这一部分：

  1. 打开浏览器窗口并导航到 GitHub 帐户。

    GitHub 登录页面为：https://github.com/login。

  2. 登录到 GitHub 帐户。

  3. 打开 GitHub 帐户菜单，然后选择“你的存储库”。

  4. 切换到“Visual Studio Code”窗口。

  5. 在 Visual Studio Code 中，打开“源代码管理”视图。

  6. 选择“发布到 GitHub”。

  7. 接受存储库的默认名称 (AccelerateDevGitHubCopilotSelect)，然后选择“发布到 GitHub 专用存储库”。

    注意

    如果未在 Visual Studio Code 中登录到 GitHub，系统会提示你登录。 登录后，使用请求的权限授权 Visual Studio Code。

  8. 在源代码管理视图中，输入“初始提交”等提交消息，然后选择“发布分支”。

  9. 请注意，Visual Studio Code 会在发布过程中显示状态消息。

    发布过程完成后，你将看到一条消息，告知你代码已成功发布到指定的 GitHub 存储库。

  10. 切换到 GitHub 帐户的浏览器窗口。

  11. 在 GitHub 帐户中打开新的 AccelerateDevGitHubCopilot 存储库。

    如果未看到 AccelerateDevGitHubCopilot 存储库，请刷新页面。 如果仍然看不到存储库，请尝试以下步骤：

    1. 切换到“Visual Studio Code”。
    2. 打开通知（发布新存储库时会生成一个通知）。
    3. 选择“在 GitHub 上打开”以打开存储库。

  12. 在 AccelerateDevGitHubCopilot 存储库的“代码”选项卡上，选择“添加 README 文件”。

  13. 在 README.md 编辑器中，键入“即将推出”，然后选择“提交更改”。

  14. 在 Commit changes 对话框中，选择“提交更改”。

  15. 切换到 Visual Studio Code 并确保“源代码管理”视图处于打开状态。

  16. 打开“视图和更多操作”菜单，然后选择“拉取”。

    可以使用“源代码管理”视图右上角的省略号打开“视图和更多操作”菜单。

  17. 打开“资源管理器”视图（而不是“解决方案资源管理器”），然后展开“AccelerateDevGitHubCopilot”文件夹。

  18. 打开 README.md 文件。

    你应会看到消息“即将推出”。

在本练习的下一部分，你将使用 GitHub Copilot Chat 更新存储库的 README 文件。

为 README 文件创建项目文档

README 文件是每个 GitHub 存储库的重要组成部分。 README 文件根据项目、项目参与者和利益干系人的需求提供信息。

对于本指导项目练习，README 文件应包含以下部分：

  • 项目标题：项目的简短清晰标题。
  • 说明：详细说明项目是什么及其用途。
  • 项目结构：项目结构的细分，包括关键文件夹和文件。
  • 键类和接口：项目中关键类和接口的列表。
  • 用法：有关如何使用项目的说明，通常包括代码示例。
  • 许可证：项目所依据的许可证。

在本练习的本部分中，你将使用 GitHub Copilot 创建项目文档，并将其添加到 README.md 文件。

请使用以下步骤完成本练习的这一部分：

  1. 打开“聊天”视图。

  2. 使用拖放操作将文件添加到聊天视图上下文。

  3. 若要为 README 文件生成项目文档，请输入以下提示：

    @workspace Generate the contents of a README.md file for the code repository. Use "Library App" as the project title. The README file should include the following sections: Description, Project Structure, Key Classes and Interfaces, Usage, License. Format all sections as raw markdown. Use a bullet list with indents to represent the project structure. Do not include ".gitignore" or the ".github", "bin", and "obj" folders.

    注意

    使用多个提示，README 文件的每个部分分别对应一个提示，可以生成更详细的结果。 为了简化过程，本练习只使用一个提示。

  4. 查看答复，确保每个部分的格式都设置为 Markdown。

    注意

    可以单独更新各个部分，以提供更详细的信息，或者在格式不正确时进行更正。 也可以将 GitHub Copilot 的答复复制到 README 文件中，然后直接在 Markdown 文件中进行更正。

  5. 将建议的文档部分复制到 README.md 文件中。

    # Library App

## Description
Library App is a console-based application for managing library operations such as patron management, book loans, and membership renewals. It uses a JSON-based data storage system and provides various services to handle library functionalities.

## Project Structure
- AccelerateDevGitHubCopilot.sln
- README.md
- src
  - `Library.ApplicationCore/`
    - `Entities/`
      - `Author.cs`
      - `Book.cs`
      - `BookItem.cs`
      - `Loan.cs`
      - `Patron.cs`
    - `Enums/`
      - `LoanExtensionStatus.cs`
      - `LoanReturnStatus.cs`
      - `MembershipRenewalStatus.cs`
    - `Interfaces/`
      - `IPatronRepository.cs`
      - `IPatronService.cs`
      - `ILoanRepository.cs`
      - `ILoanService.cs`
    - `Library.ApplicationCore.csproj`
    - `Services/`
      - `PatronService.cs`
      - `LoanService.cs`
  - `Library.Console/`
    - `appSettings.json`
    - `CommonActions.cs`
    - `ConsoleApp.cs`
    - `ConsoleState.cs`
    - `Library.Console.csproj`
    - `Program.cs`
  - `Library.Infrastructure/`
    - `Data/`
      - `JsonData.cs`
      - `JsonLoanRepository.cs`
      - `JsonPatronRepository.cs`
    - `Library.Infrastructure.csproj`
- tests
  - `UnitTests/`
    - `ApplicationCore/`
      - `LoanService/`
        - `ReturnLoan.cs`
        - `ExtendLoan.cs`
      - `PatronService/`
        - `RenewMembership.cs`
    - `UnitTests.csproj`

## Key Classes and Interfaces
- **Entities**
  - **Author**: Represents an author with properties like `Id` and `Name`.
  - **Book**: Represents a book with properties like `Id`, `Title`, `AuthorId`, `Genre`, `ImageName`, and `ISBN`.
  - **BookItem**: Represents a specific copy of a book with properties like `Id`, `BookId`, `AcquisitionDate`, and `Condition`.
  - **Loan**: Represents a loan with properties like `Id`, `BookItemId`, `PatronId`, `LoanDate`, `DueDate`, and `ReturnDate`.
  - **Patron**: Represents a library patron with properties like `Id`, `Name`, `MembershipStart`, `MembershipEnd`, and `Loans`.

- **Enums**
  - **LoanExtensionStatus**: Enum for loan extension statuses.
  - **LoanReturnStatus**: Enum for loan return statuses.
  - **MembershipRenewalStatus**: Enum for membership renewal statuses.

- **Interfaces**
  - **IPatronRepository**: Interface for patron repository with methods like `GetPatron`, `SearchPatrons`, and `UpdatePatron`.
  - **IPatronService**: Interface for patron service with method `RenewMembership`.
  - **ILoanRepository**: Interface for loan repository with methods like `GetLoan` and `UpdateLoan`.
  - **ILoanService**: Interface for loan service with methods like `ReturnLoan` and `ExtendLoan`.

- **Services**
  - **PatronService**: Implements `IPatronService` to handle patron-related operations.
  - **LoanService**: Implements `ILoanService` to handle loan-related operations.

- **Console**
  - **ConsoleApp**: Main console application class that handles user interactions and application flow.
  - **ConsoleState**: Enum for different states of the console application.
  - **CommonActions**: Enum for common actions in the console application.

- **Infrastructure**
  - **JsonData**: Handles loading and saving data to JSON files.
  - **JsonLoanRepository**: Implements `ILoanRepository` to manage loan data.
  - **JsonPatronRepository**: Implements `IPatronRepository` to manage patron data.

## Usage
1. Clone the repository.
2. Open the solution file AccelerateDevGitHubCopilot.sln in Visual Studio.
3. Build the solution to restore dependencies.
4. Run the `Library.Console` project to start the console application.
5. Follow the on-screen instructions to search for patrons, view patron details, extend loans, return books, and renew memberships.

## License
This project is licensed under the MIT License.

  6. 根据需要手动调整格式，然后保存更新后的 README.md 文件。

  7. 打开 Visual Studio Code 的“源代码管理”视图。

  8. 若要让 GitHub Copilot 生成提交消息，请选择消息框右侧的图标。

    你应会看到一条类似于以下消息的提交消息：

    chore: Update README.md with project description and usage instructions

  9. 暂存并提交文件更新。

  10. 将更新同步（或推送）到 GitHub 存储库。

检查你的工作

若要检查工作成果，请完成以下步骤：

  1. 打开 AccelerateDevGitHubCopilot 项目的 GitHub 存储库。

  2. 使用“代码”选项卡查看更新后的 README.md 文件。

  3. 确保 README 文件中描述的项目结构与存储库的文件夹结构一致。

  4. 查看提交历史记录并找到 GitHub Copilot 生成的提交消息。