Exercício: Analisar e documentar código usando as ferramentas do GitHub Copilot

20 minutos

O GitHub Copilot pode ajudar você a entender e documentar uma base de código gerando explicações e documentação. Neste exercício, você usará o GitHub Copilot para analisar e documentar o aplicativo de biblioteca. Você também criará um repositório GitHub para o aplicativo de biblioteca e gerará um arquivo LEIAME para o repositório usando o GitHub Copilot.

Esse exercício inclui as seguintes tarefas:

Usar o GitHub Copilot para explicar a base de código do aplicativo de biblioteca.
Usar o Visual Studio Code para criar um repositório GitHub para o aplicativo de biblioteca.
Usar extensões do GitHub Copilot para analisar a solução e criar um arquivo LEIAME.md para o repositório.

Examinar a base de código do aplicativo de biblioteca

Antes de criar um repositório de código e um arquivo LEIAME, você deve levar algum tempo para examinar a base de código. É importante entender a arquitetura do aplicativo e os principais recursos antes de documentar o projeto. Você também deve executar o aplicativo para garantir que ele seja executado conforme o esperado.

Usar o GitHub Copilot para explicar a base de código do aplicativo de biblioteca

O GitHub Copilot pode ajudá-lo a entender uma base de código desconhecida gerando explicações nos níveis de solução e recursos.

Use as seguintes etapas para concluir esta seção do exercício:

Verifique se a solução AccelerateDevGitHubCopilot está aberta no Visual Studio Code.
Abra o modo de exibição chat e, em seguida, insira um prompt que usa o participante @workspace do GitHub Copilot para gerar uma descrição do projeto.

Por exemplo, insira a seguinte solicitação no modo de exibição de chat:
```
@workspace Describe this project
```

Reserve alguns minutos para examinar a resposta.

Você deverá ver uma resposta semelhante à seguinte descrição:

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.

Use o modo de exibição Gerenciador de Soluções para expandir as pastas do projeto.
Localize e abra o arquivo ConsoleApp.cs.

O arquivo ConsoleApp.cs está localizado na pasta src/Library.Console.
Insira um prompt no modo de exibição chat que gera uma descrição da classe ConsoleApp.

Por exemplo, insira a seguinte solicitação no modo de exibição de chat:
```
@workspace #editor Describe the ConsoleApp class
```

Reserve alguns minutos para examinar a resposta.

Você deverá ver uma resposta semelhante à seguinte descrição:

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.

Abra o arquivo Program.cs.
Insira um prompt no modo de exibição chat que gera uma descrição do arquivo Program.cs.

Por exemplo, insira a seguinte solicitação no modo de exibição de chat:
```
@workspace #editor Describe the Program.cs file
```

Reserve alguns minutos para examinar a resposta.

Você deverá ver uma resposta semelhante à seguinte descrição:

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.

Expanda a pasta de projeto Library.Infrastructure.
Adicione os arquivos JsonData.cs, JsonLoanRepository.cs e JsonPatronRepository.cs ao contexto do Chat.

Use o botão Anexar Contexto para adicionar os arquivos ao contexto do Chat. Você também pode usar uma operação de arrastar e soltar para adicionar os arquivos ao contexto do Chat.
Insira um prompt no modo de exibição chat que gera uma explicação das classes de acesso a dados.

Por exemplo, insira a seguinte solicitação no modo de exibição de chat:
```
@workspace /explain Explain how the data access classes work
```

Reserve alguns minutos para examinar a resposta.

Você deverá ver uma resposta semelhante à seguinte descrição:

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.

Leve alguns minutos para examinar os arquivos de dados JSON usados para simular registros de biblioteca.

Os arquivos de dados JSON estão localizados na pasta src/Library.Console/Json.

Os arquivos de dados usam propriedades de ID para vincular entidades. Por exemplo, um objeto Loan tem uma propriedade PatronId que é vinculada a um objeto Patron com a mesma ID. Os arquivos JSON contêm dados para autores, livros, itens de livro, clientes e empréstimos.

Observação

Observe que nomes de autor, títulos de livro e nomes de cliente foram anonimizados para fins deste projeto guiado.

Compile e execute o aplicativo

A execução do aplicativo ajudará você a entender a interface do usuário, os principais recursos do aplicativo e como os componentes do aplicativo interagem.

Use as seguintes etapas para concluir esta seção do exercício:

Verifique se você tem a exibição do Gerenciador de Soluções aberta.

A exibição do Gerenciador de Soluções não é a mesma que a exibição do Explorer. A exibição do Gerenciador de Soluções usa arquivos de projeto e solução como nós de “diretório” para exibir a estrutura da solução.
Para executar o aplicativo, clique com o botão direito do mouse em Library.Console, selecione Depurar e, em seguida, selecione Iniciar Nova Instância.

Se as opções Depurar e Iniciar Nova Instância não forem exibidas, verifique se você está usando a exibição do Gerenciador de Soluções e não a exibição do Explorer.

As etapas a seguir orientam você por um caso de uso simples.
Quando solicitado a obter um nome de cliente, digite Um e pressione Enter.

Você deverá ver uma lista de leitores que correspondam à consulta da pesquisa.

Observação

O aplicativo usa um processo de pesquisa que diferencia maiúsculas de minúsculas.
No prompt "Opções de Entrada", digite 2 e pressione Enter.

A inserção 2 seleciona o segundo cliente na lista.

Você deverá ver o nome do leitor e o status de filiação seguidos dos detalhes do empréstimo do livro.
No prompt "Opções de Entrada", digite 1 e pressione Enter.

Inserir 1 seleciona o primeiro livro da lista.

Você deve ver os detalhes do livro listados, incluindo a data de conclusão e o status de retorno.
No prompt "Opções de Entrada", digite r e pressione Enter.

Inserindo r retorna o livro.
Verifique se a mensagem “Livro foi retornado com sucesso” é exibida.

A mensagem “O livro foi retornado com êxito” deve ser seguida pelos detalhes do livro. Os livros retornados são marcados com Returned: True.
Para iniciar uma nova pesquisa, digite s e pressione Enter.
Quando solicitado a obter um nome de cliente, digite Um e pressione Enter.
No prompt "Opções de Entrada", digite 2 e pressione Enter.
Verifique se o primeiro empréstimo do livro está marcado como Returned: True.
No prompt "Opções de Entrada", digite q e pressione Enter.
Interrompa a sessão de depuração.

Criar o repositório GitHub para seu código

A criação do repositório GitHub para seu código permitirá que você compartilhe seu trabalho com outras pessoas e colabore no projeto.

Observação

Use sua própria conta do GitHub para criar um repositório GitHub privado para o aplicativo de biblioteca.

Use as seguintes etapas para concluir esta seção do exercício:

Abra uma janela do navegador e navegue até sua conta GitHub.

A página de logon do GitHub é: https://github.com/login.
Entre na sua conta do GitHub.
Abra o menu da conta do GitHub e selecione Seus repositórios.
Volte para a janela do Visual Studio Code.
No Visual Studio Code, abra o modo de exibição controle do código-fonte.
Selecione Publicar no GitHub.
Aceite o nome padrão do repositório (AccelerateDevGitHubCopilotSelect) e selecione Publicar no repositório privado do GitHub.

Observação

Se não estiver conectado ao GitHub no Visual Studio Code, você será solicitado a entrar. Após ter entrado, autorize o Visual Studio Code com as permissões solicitadas.
No modo de exibição Controle do Código-Fonte, insira uma mensagem de commit como, por exemplo, "Commit inicial" e, a seguir, selecione Publicar ramificação.
Observe que o Visual Studio Code exibe mensagens de status durante o processo de publicação.

Quando o processo de publicação for concluído, você verá uma mensagem informando que seu código foi publicado com êxito no repositório GitHub especificado.
Alterne para a janela do navegador para sua conta do GitHub.
Abra o novo repositório AccelerateDevGitHubCopilot em sua conta do GitHub.

Se você não vir seu repositório AccelerateDevGitHubCopilot, atualize a página. Se você ainda não vir o repositório, tente as seguintes etapas:
1. Mude para o Visual Studio Code.
2. Abra suas notificações (uma notificação foi gerada quando o novo repositório foi publicado).
3. Selecione Abrir no GitHub para abrir o repositório.
Na guia Código do repositório AccelerateDevGitHubCopilot, selecione Adicionar um arquivo LEIAME.
No editor de README.md, digite Em breve e selecione Confirmar alterações.
Commit changes Na caixa de diálogo, selecione Confirmar alterações.
Alterne para o Visual Studio Code e verifique se o modo de exibição controle do código-fonte está aberto.
Abra o menu Exibições e Mais Ações e selecione Pull.

O menu Exibições e Mais Ações pode ser aberto usando as reticências no canto superior direito do modo de exibição controle do código-fonte.
Abra a exibição do Explorer (não o Gerenciador de Soluções) e expanda a pasta AccelerateDevGitHubCopilot .
Abra o arquivo LEIAME.md.

Você verá a mensagem “Em breve”.

Você usará o GitHub Copilot Chat para atualizar o arquivo LEIAME do repositório na próxima seção deste exercício.

Criar a documentação do projeto para o arquivo LEIAME

O arquivo LEIAME é uma parte essencial de qualquer repositório GitHub. O LEIAME fornece informações com base nas necessidades do projeto, colaboradores do projeto e stakeholders.

Para este exercício de projeto guiado, seu arquivo LEIAME deve incluir as seguintes seções:

Título do Projeto: Um título breve e claro para o projeto.
Descrição: uma explicação detalhada do que é o projeto e o que ele faz.
Estrutura do Projeto: um detalhamento da estrutura do projeto, incluindo pastas de chave e arquivos.
Classes-chave e interfaces: uma lista de classes-chave e interfaces no projeto.
Uso: instruções sobre como usar o projeto, geralmente incluindo exemplos de código.
Licença: a licença sob a qual o projeto está.

Nesta seção do exercício, você usará o GitHub Copilot para criar a documentação do projeto e adicioná-la ao arquivo README.md.

Use as seguintes etapas para concluir esta seção do exercício:

Abra o modo de exibição de chat.
Use as operações de arrastar e soltar para adicionar arquivos ao contexto de exibição do Chat.

Para gerar a documentação do projeto do arquivo LEIAME, insira o seguinte prompt:

@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.

Observação

Usando vários prompts, um para cada seção do arquivo LEIAME produziria resultados mais detalhados. Um único prompt é usado neste exercício para simplificar o processo.

Examine a resposta para garantir que cada seção seja formatada como markdown.

Observação

Você pode atualizar as seções individualmente para fornecer informações mais detalhadas ou se elas não estiverem formatadas corretamente. Você também pode copiar a resposta do GitHub Copilot para o arquivo LEIAME e, em seguida, fazer correções diretamente no arquivo de markdown.

Copie as seções de documentação sugeridas para o arquivo LEIAME.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.

Ajuste a formatação manualmente se necessário e, a seguir, salve o arquivo README.md atualizado.
Abra a exibição Controle de Código-Fonte do Visual Studio Code.
Para que o GitHub Copilot gere uma mensagem de confirmação, selecione o ícone no lado direito da caixa de mensagem.

Você deverá ver uma mensagem de confirmação semelhante à seguinte mensagem:
```
chore: Update README.md with project description and usage instructions
```
Preparar e confirmar as atualizações de arquivo.
Sincronize (ou envie por push) suas atualizações para o repositório GitHub.

Verifique seu trabalho

Para verificar seu trabalho, conclua as seguintes etapas:

Abra o repositório GitHub para o projeto AccelerateDevGitHubCopilot.
Use a guia Código para examinar o arquivo de README.md atualizado.
Verifique se a estrutura do projeto descrita no arquivo LEIAME alinha a estrutura de pastas do repositório.
Examine o histórico de confirmação e localize a mensagem de confirmação gerada pelo GitHub Copilot.

Comentários

Esta página foi útil?