Esercizio: analizzare e documentare il codice usando gli strumenti di GitHub Copilot

20 minuti

GitHub Copilot consente di comprendere e documentare una codebase generando spiegazioni e documentazione. In questo esercizio si userà GitHub Copilot per analizzare e documentare l'applicazione della biblioteca. Verrà creato anche un repository GitHub per l'applicazione della biblioteca e si genererà un file README per il repository usando GitHub Copilot.

Questo esercizio include le seguenti attività:

Usare GitHub Copilot per spiegare la codebase dell'applicazione della biblioteca.
Usare Visual Studio Code per creare un repository GitHub per l'applicazione della biblioteca.
Usare le estensioni di GitHub Copilot per analizzare la soluzione e creare un file README.md per il repository.

Esaminare la codebase dell'applicazione della biblioteca

Prima di creare un repository di codice e un file README, è necessario dedicare un po' tempo all'esame della codebase. È importante comprendere l'architettura dell'app e le funzionalità principali prima di documentare il progetto. È anche necessario eseguire l'applicazione per assicurarsi che funzioni come previsto.

Usare GitHub Copilot per spiegare la codebase dell'applicazione della biblioteca

GitHub Copilot consente di comprendere una codebase non familiare generando spiegazioni a livello di soluzione e funzionalità.

Per completare questa sezione dell'esercizio, seguire questa procedura:

Assicurarsi che la soluzione AccelerateDevGitHubCopilot sia aperta in Visual Studio Code.
Aprire la vista Chat e quindi immettere un prompt che usa il partecipante @workspace di GitHub Copilot per generare una descrizione del progetto.

Ad esempio, immettere il prompt seguente nella vista Chat:
```
@workspace Describe this project
```

Dedicare qualche altro istante all'esame della risposta.

La risposta dovrebbe essere simile alla descrizione seguente:

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.

Usare la vista Esplora soluzioni per espandere le cartelle del progetto.
Individuare e aprire il file ConsoleApp.cs .

Il file ConsoleApp.cs si trova nella cartella src/Library.Console.
Immettere un prompt nella vista Chat che genera una descrizione della classe ConsoleApp.

Ad esempio, immettere il prompt seguente nella vista Chat:
```
@workspace #editor Describe the ConsoleApp class
```

Dedicare qualche altro istante all'esame della risposta.

La risposta dovrebbe essere simile alla descrizione seguente:

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.

Apri il file Program.cs.
Immettere un prompt nella vista Chat che genera una descrizione del file Program.cs.

Ad esempio, immettere il prompt seguente nella vista Chat:
```
@workspace #editor Describe the Program.cs file
```

Dedicare qualche altro istante all'esame della risposta.

La risposta dovrebbe essere simile alla descrizione seguente:

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.

Espandere la cartella del progetto Library.Infrastructure.
Aggiungere i file JsonData.cs, JsonLoanRepository.cse JsonPatronRepository.cs al contesto di Chat.

Usare il pulsante Collega contesto per aggiungere i file al contesto della chat. È anche possibile usare un'operazione di trascinamento della selezione per aggiungere i file al contesto di Chat.
Immettere un prompt nella vista Chat che genera una spiegazione delle classi di accesso ai dati.

Ad esempio, immettere il prompt seguente nella vista Chat:
```
@workspace /explain Explain how the data access classes work
```

Dedicare qualche altro istante all'esame della risposta.

La risposta dovrebbe essere simile alla descrizione seguente:

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.

Dedicare qualche minuto all'esame dei file di dati JSON usati per simulare i record della biblioteca.

I file di dati JSON si trovano nella cartella src/Library.Console/Json.

I file di dati usano proprietà ID per collegare le entità. Ad esempio, un oggetto Loan ha una proprietà PatronId che collega a un oggetto Patron con lo stesso ID. I file JSON contengono dati per autori, libri, numeri di libri, clienti e prestiti.

Nota

Si noti che i nomi degli autori, i titoli dei libri e i nomi dei clienti sono stati resi anonimi per gli scopi di questo progetto guidato.

Compilare ed eseguire l'applicazione

L'esecuzione dell'applicazione consente di comprendere l'interfaccia utente, le funzionalità principali dell'applicazione e il modo in cui interagiscono i componenti dell'app.

Per completare questa sezione dell'esercizio, seguire questa procedura:

Assicurarsi che la vista Esplora soluzioni sia aperta.

La vista Esplora soluzioni non è identica alla vista Esplora risorse. La vista Esplora soluzioni usa file di progetto e soluzione come nodi "directory" per visualizzare la struttura della soluzione.
Per eseguire l'applicazione, fare clic con il pulsante destro del mouse su Library.Console, selezionare Debug e quindi selezionare Avvia nuova istanza.

Se le opzioni Debug e Avvia nuova istanza non vengono visualizzate, assicurarsi di usare la vista Esplora soluzioni e non la vista Esplora risorse.

I passaggi seguenti forniscono una guida per un case use semplice.
Quando viene chiesto il nome di un cliente, digitare Uno e quindi premere Invio.

Verrà visualizzato un elenco di clienti che corrispondono alla query di ricerca.

Nota

L'applicazione usa un processo di ricerca con distinzione tra maiuscole e minuscole.
Al prompt "Opzioni di input", digitare 2 e quindi premere Invio.

Se si immette 2, viene selezionato il secondo cliente nell'elenco.

Deve essere visualizzato il nome e lo stato di adesione del cliente seguito dai dettagli del prestito del libro.
Al prompt "Opzioni di input", digitare 1 e quindi premere Invio.

Se si immette 1, viene selezionato il primo libro nell'elenco.

Dovrebbero essere elencati i dettagli del libro, tra cui la data di scadenza e lo stato di restituzione.
Al prompt "Opzioni di input", digitare r e quindi premere Invio.

Se si immette r, viene restituito il libro.
Assicurarsi che venga visualizzato il messaggio "Il libro è stato restituito correttamente".

Il messaggio "Il libro è stato restituito correttamente" deve essere seguito dai dettagli del libro. I libri restituiti sono contrassegnati con Returned: True.
Per iniziare una nuova ricerca, digitare s e quindi premere Invio.
Quando viene chiesto il nome di un cliente, digitare Uno e quindi premere Invio.
Al prompt "Opzioni di input", digitare 2 e quindi premere Invio.
Assicurarsi che il primo prestito del libro sia contrassegnato Returned: True.
Al prompt "Opzioni di input", digitare q e quindi premere Invio.
Arrestare la sessione di debug

Creare il repository GitHub per il codice

La creazione del repository GitHub per il codice consentirà di condividere il lavoro con altri utenti e collaborare al progetto.

Nota

Viene usato il proprio account GitHub per creare un repository GitHub privato per l'applicazione della biblioteca.

Per completare questa sezione dell'esercizio, seguire questa procedura:

Aprire una finestra del browser e passare al proprio account GitHub.

La pagina di accesso di GitHub è: https://github.com/login.
Accedi all'account GitHub.
Aprire il menu dell'account GitHub e quindi selezionare Repository.
Tornare alla finestra di Visual Studio Code.
Aprire la vista Controllo del codice sorgente in Visual Studio Code.
Selezionare Pubblica in GitHub.
Accettare il nome predefinito per il repository (AccelerateDevGitHubCopilotSelect) e selezionare Pubblica nel repository privato GitHub.

Nota

Se non si è connessi a GitHub in Visual Studio Code, verrà richiesto di eseguire l'accesso. Dopo aver eseguito l'accesso, autorizzare Visual Studio Code con le autorizzazioni richieste.
Nella visualizzazione Controllo del codice sorgente immettere un messaggio di commit, ad esempio "Commit iniziale", quindi selezionare Publish Branch.
Si noti che Visual Studio Code visualizza messaggi di stato durante il processo di pubblicazione.

Al termine del processo di pubblicazione, verrà visualizzato un messaggio che informa che il codice è stato pubblicato correttamente nel repository GitHub specificato.
Passare alla finestra del browser per il proprio account GitHub.
Aprire il nuovo repository AccelerateDevGitHubCopilot nel proprio account GitHub.

Se il repository AccelerateDevGitHubCopilot non viene visualizzato, aggiornare la pagina. Se il repository non viene ancora visualizzato, provare i passaggi seguenti:
1. Passare a Visual Studio Code.
2. Aprire le notifiche (è stata generata una notifica quando è stato pubblicato il nuovo repository).
3. Selezionare Apri in GitHub per aprire il repository.
Nella scheda Codice del repository AccelerateDevGitHubCopilot, selezionare Aggiungi un README.
Nell'editor di README.mdm digitare Presto disponibile e quindi selezionare Esegui il commit delle modifiche.
Nella finestra di dialogo Commit changes, selezionare Esegui il commit delle modifiche.
Passare a Visual Studio Code e assicurarsi che la vista Controllo del codice sorgente sia aperta.
Aprire il menu Viste e altre azioni e quindi selezionare Pull.

È possibile aprire il menu Viste e altre azioni usando i puntini di sospensione nell'angolo superiore destro della vista Controllo del codice sorgente.
Aprire la vista Esplora risorse (non Esplora soluzioni) e quindi espandere la cartella AccelerateDevGitHubCopilot.
Creare il file README.md.

Dovrebbe essere visualizzato il messaggio "Presto disponibile".

Si userà GitHub Copilot Chat per aggiornare il file README del repository nella sezione successiva di questo esercizio.

Creare la documentazione del progetto per il file README

Il file README è una parte essenziale di qualsiasi repository GitHub. Il README fornisce informazioni in base alle esigenze del progetto, ai collaboratori del progetto e agli interessati.

Per questo esercizio di progetto guidato, il file README deve includere le sezioni seguenti:

Titolo progetto: Breve titolo chiaro per il progetto.
Descrizione: Spiegazione dettagliata del progetto e delle relative operazioni.
Struttura del progetto: Una scomposizione della struttura del progetto, incluse le cartelle e i file chiave.
Principali classi e interfacce: Un elenco di classi e interfacce chiave nel progetto.
Utilizzo: Istruzioni su come usare il progetto, che includono spesso esempi di codice.
Licenza: Licenza associata al progetto.

In questa sezione dell'esercizio si userà GitHub Copilot per creare la documentazione del progetto e aggiungerla al file README.md.

Per completare questa sezione dell'esercizio, seguire questa procedura:

Aprire la vista Chat.
Usare le operazioni di trascinamento della selezione per aggiungere file al contesto di visualizzazione Chat.

Per generare la documentazione del progetto per il file README, immettere il prompt seguente:

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

Nota

Usando più prompt, uno per ogni sezione del file README, vengono prodotti risultati più dettagliati. In questo esercizio viene usato un singolo prompt per semplificare il processo.

Esaminare la risposta per assicurarsi che ogni sezione sia formattata come markdown.

Nota

È possibile aggiornare le sezioni singolarmente per fornire informazioni più dettagliate o se non sono formattate correttamente. È anche possibile copiare la risposta di GitHub Copilot nel file README e quindi apportare correzioni direttamente nel file markdown.

Copiare le sezioni della documentazione suggerite nel file 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.

Modificare la formattazione manualmente, se necessario, e quindi salvare il file di README.md aggiornato.
Aprire la visualizzazione Controllo del codice sorgente di Visual Studio Code.
Per fare in modo che GitHub Copilot generi un messaggio di commit, selezionare l'icona a destra della finestra del messaggio.

Verrà visualizzato un messaggio di commit simile al messaggio seguente:
```
chore: Update README.md with project description and usage instructions
```
Preparare ed eseguire il commit degli aggiornamenti del file.
Sincronizzare (o eseguire il push) gli aggiornamenti nel repository GitHub.

Controlla il tuo lavoro

Per controllare il lavoro, completare i passaggi seguenti:

Aprire il repository GitHub per il progetto AccelerateDevGitHubCopilot.
Usare la scheda Codice per esaminare il file README.md aggiornato.
Assicurarsi che la struttura del progetto descritta nel file README sia allineata alla struttura di cartelle del repository.
Esaminare la cronologia dei commit e individuare il messaggio di commit generato da GitHub Copilot.

Commenti e suggerimenti

Questa pagina è stata utile?