Refactor IPAM model classes to use records for Address, Subnetwork, Vlan, Vrf, Section, Tag, Domain, Nameserver, and Session; enhance documentation and implement value equality for records.

classlib/Cmdlets/NewSessionCmdlet.cs

@@ -1,18 +1,22 @@
 namespace PS.IPAM.Cmdlets;
+
 using System;
 using System.Management.Automation;
-using System.Threading.Tasks;
-using PS.IPAM;
 using PS.IPAM.Helpers;
 
+/// <summary>
+/// Creates a new phpIPAM API session.
+/// </summary>
 [Cmdlet(VerbsCommon.New, "Session", DefaultParameterSetName = "Credentials")]
-public class NewSessionCmdlet : PSCmdlet
+[OutputType(typeof(Session))]
+public class NewSessionCmdlet : BaseCmdlet
 {
     [Parameter(
         Mandatory = true,
         ValueFromPipeline = true,
         ValueFromPipelineByPropertyName = true,
-        Position = 0)]
+        Position = 0,
+        HelpMessage = "The phpIPAM server URL (must start with http:// or https://).")]
     [ValidateNotNullOrEmpty]
     [ValidatePattern("^https?://")]
     public string URL { get; set; } = string.Empty;
@@ -21,7 +25,8 @@ public class NewSessionCmdlet : PSCmdlet
         Mandatory = true,
         ValueFromPipeline = true,
         ValueFromPipelineByPropertyName = true,
-        Position = 1)]
+        Position = 1,
+        HelpMessage = "The API application ID configured in phpIPAM.")]
     [ValidateNotNullOrEmpty]
     public string AppID { get; set; } = string.Empty;
 
@@ -30,7 +35,8 @@ public class NewSessionCmdlet : PSCmdlet
         ValueFromPipeline = true,
         ValueFromPipelineByPropertyName = true,
         Position = 2,
-        ParameterSetName = "Credentials")]
+        ParameterSetName = "Credentials",
+        HelpMessage = "The credentials (username and password) for authentication.")]
     [ValidateNotNullOrEmpty]
     public PSCredential? Credentials { get; set; }
 
@@ -39,7 +45,8 @@ public class NewSessionCmdlet : PSCmdlet
         ValueFromPipeline = true,
         ValueFromPipelineByPropertyName = true,
         Position = 2,
-        ParameterSetName = "Token")]
+        ParameterSetName = "Token",
+        HelpMessage = "The static API token for authentication.")]
     [ValidateNotNullOrEmpty]
     public string? Token { get; set; }
 
@@ -47,7 +54,8 @@ public class NewSessionCmdlet : PSCmdlet
         Mandatory = false,
         ValueFromPipeline = true,
         ValueFromPipelineByPropertyName = true,
-        Position = 3)]
+        Position = 3,
+        HelpMessage = "If specified, SSL certificate errors will be ignored.")]
     public SwitchParameter IgnoreSSL { get; set; }
 
     protected override void ProcessRecord()
@@ -55,9 +63,10 @@ public class NewSessionCmdlet : PSCmdlet
         try
         {
             Session session;
+
             if (ParameterSetName == "Credentials" && Credentials != null)
             {
-                session = SessionManager.CreateSessionWithCredentials(
+                session = SessionManager.CreateSessionWithCredentialsAsync(
                     URL,
                     AppID,
                     Credentials,
@@ -70,12 +79,14 @@ public class NewSessionCmdlet : PSCmdlet
             }
             else
             {
-                throw new ArgumentException("Invalid parameter set");
+                throw new ArgumentException("Invalid parameter set. Provide either Credentials or Token.");
             }
+
+            WriteObject(session);
         }
         catch (Exception ex)
         {
-            WriteError(new ErrorRecord(ex, "NewSessionError", ErrorCategory.InvalidOperation, null));
+            WriteError(new ErrorRecord(ex, "NewSessionError", ErrorCategory.AuthenticationError, null));
         }
     }
 }