PSOPNSenseAPI/docs/Visual-Studio-Solution.md

Visual Studio Solution

This document provides information about the Visual Studio solution for the PSOPNSenseAPI project.

Overview

The PSOPNSenseAPI solution is a Visual Studio solution that contains the source code for the PSOPNSenseAPI PowerShell module. The solution is designed to be opened in Visual Studio for development, debugging, and troubleshooting.

Solution Structure

The solution contains the following projects:

• PSOPNSenseAPI: The main project containing the PowerShell module code.
• PSOPNSenseAPI.Tests: The test project containing unit tests for the PowerShell module.

Opening the Solution

To open the solution in Visual Studio:

1. Launch Visual Studio
2. Select "Open a project or solution"
3. Navigate to the root directory of the PSOPNSenseAPI repository
4. Select the PSOPNSenseAPI.sln file
5. Click "Open"

Building the Solution

To build the solution in Visual Studio:

1. Open the solution in Visual Studio
2. Select the desired build configuration (Debug or Release) from the dropdown in the toolbar
3. Select "Build > Build Solution" from the menu or press F6

Alternatively, you can build the solution from the command line using the build scripts:

# Build the module
.\build\build.ps1

# Build a release version with automatic versioning
.\build\build-release.ps1 -Clean -Test -Package

Debugging

To debug the module in Visual Studio:

1. Open the solution in Visual Studio
2. Set breakpoints in the code
3. Select "Debug > Start Debugging" from the menu or press F5

For debugging PowerShell cmdlets, you can also use the PowerShell Integrated Scripting Environment (ISE) or Visual Studio Code with the PowerShell extension.

Troubleshooting IPNetwork2 Issues

If you encounter issues with the IPNetwork2 library, here are some common troubleshooting steps:

1. Check the reference: Ensure that the IPNetwork2 package is properly referenced in the project file.

   <PackageReference Include="IPNetwork2" Version="3.1.764" />
   

2. Verify the namespace: The correct namespace for IPNetwork2 is System.Net.

   using System.Net;
   

3. Check the class name: The main class in IPNetwork2 is IPNetwork, not IPNetwork2.

   // Correct usage
   System.Net.IPNetwork network = System.Net.IPNetwork.Parse("192.168.1.0/24");
   
   // Incorrect usage
   IPNetwork2 network = IPNetwork2.Parse("192.168.1.0/24");
   

4. Update package references: If you're still having issues, try updating the package reference to the latest version.

   # In Package Manager Console
   Update-Package IPNetwork2
   

5. Restore NuGet packages: Ensure all NuGet packages are properly restored.

   # In Package Manager Console
   Restore-Package
   

6. Clean and rebuild: Sometimes a clean rebuild can resolve reference issues.

   # In Package Manager Console
   Clean-Project
   Build-Project
   

Adding New Features

When adding new features to the solution:

1. Create appropriate model classes in the Models directory
2. Implement service classes in the Services directory
3. Create PowerShell cmdlets in the Cmdlets directory
4. Update the module manifest (PSOPNSenseAPI.psd1) to export the new cmdlets
5. Add tests for the new features in the PSOPNSenseAPI.Tests project
6. Update documentation

Testing

The solution includes unit tests that can be run from Visual Studio using the Test Explorer or from the command line:

# Run tests
.\build\test.ps1

Release Process

The project includes a script to automate the release process. To create a new release:

1. Run the scripts\Create-Release.ps1 script
2. Follow the instructions to create a GitHub release

The script will:

1. Update the version in the project file and module manifest to the current date and time (yyyy.MM.dd.HHmm)
2. Build the solution in Release mode
3. Copy the DLLs to the output folder
4. Create a zip file of the module
5. Clean up old zip files, keeping only the latest one
6. Commit and push the changes
7. Create a release note file

After running the script, you'll need to manually create a GitHub release and attach the zip file.

Dependencies

The solution has the following dependencies:

• PowerShellStandard.Library (5.1.1)
• Newtonsoft.Json (13.0.3)
• System.Net.Http (4.3.4)
• IPNetwork2 (3.1.764)

Notes

• The solution is configured to target both .NET Framework 4.7.2 and .NET Standard 2.0 to support both Windows PowerShell 5.1 and PowerShell 7+.
• The module uses a versioning scheme of yyyy.MM.dd.HHmm for releases.
• The solution includes XML documentation comments that are used to generate help content for the PowerShell cmdlets.
• The module uses System.Reflection.Assembly::LoadBytes to load DLLs to avoid file lock issues.
• DLLs are organized in a lib subfolder for neatness.

Module Structure

The module has the following structure:

PSOPNSenseAPI/
├── lib/                  # DLL files
│   ├── Newtonsoft.Json.dll
│   ├── PSOPNSenseAPI.dll
│   ├── System.Net.IPNetwork.dll
│   └── ...
├── PSOPNSenseAPI.psd1    # Module manifest
└── PSOPNSenseAPI.psm1    # Module script that loads DLLs

The PSM1 file uses System.Reflection.Assembly::LoadBytes to load the DLLs from the lib folder, which avoids file lock issues that can occur when PowerShell loads DLLs directly.