diff --git a/src/PSProxmoxVE.Core/Authentication/PveAuthMode.cs b/src/PSProxmoxVE.Core/Authentication/PveAuthMode.cs index 2691ba3..b7a0bd0 100644 --- a/src/PSProxmoxVE.Core/Authentication/PveAuthMode.cs +++ b/src/PSProxmoxVE.Core/Authentication/PveAuthMode.cs @@ -1,9 +1,12 @@ namespace PSProxmoxVE.Core.Authentication { - /// Authentication mode for Proxmox VE API + /// Authentication mode for Proxmox VE API. public enum PveAuthMode { + /// Authenticate using a username/password ticket and CSRF token. Ticket, + + /// Authenticate using a persistent API token (USER@REALM!TOKENID=UUID). ApiToken } } diff --git a/src/PSProxmoxVE.Core/Authentication/PveSession.cs b/src/PSProxmoxVE.Core/Authentication/PveSession.cs index 3e1d50a..80bb098 100644 --- a/src/PSProxmoxVE.Core/Authentication/PveSession.cs +++ b/src/PSProxmoxVE.Core/Authentication/PveSession.cs @@ -3,17 +3,34 @@ using PSProxmoxVE.Core.Models; namespace PSProxmoxVE.Core.Authentication { - /// Represents an authenticated session to a Proxmox VE server + /// Represents an authenticated session to a Proxmox VE server. public class PveSession { + /// The hostname or IP address of the Proxmox VE server. public string Hostname { get; } + + /// The TCP port of the Proxmox VE API (default 8006). public int Port { get; } + + /// Whether to skip TLS certificate validation when connecting. public bool SkipCertificateCheck { get; } + + /// The authentication mode used for this session. public PveAuthMode AuthMode { get; } + + /// The API token string, when using API token authentication. public string? ApiToken { get; } + + /// The session ticket cookie value, when using ticket authentication. public string? Ticket { get; } + + /// The CSRF prevention token, when using ticket authentication. public string? CsrfToken { get; } + + /// The UTC expiry time for the session ticket. public DateTime TicketExpiry { get; } + + /// The Proxmox VE version detected on the server at connection time. public PveVersion? ServerVersion { get; internal set; } /// Returns true if the ticket has expired (only relevant for Ticket auth mode) diff --git a/src/PSProxmoxVE.Core/Authentication/PveVersion.cs b/src/PSProxmoxVE.Core/Authentication/PveVersion.cs index ebcdac3..470a0f9 100644 --- a/src/PSProxmoxVE.Core/Authentication/PveVersion.cs +++ b/src/PSProxmoxVE.Core/Authentication/PveVersion.cs @@ -2,12 +2,18 @@ using System; namespace PSProxmoxVE.Core.Authentication { - /// Represents a Proxmox VE server version (major.minor only) + /// Represents a Proxmox VE server version (major.minor only). public class PveVersion { + /// The major version number (e.g., 8 in PVE 8.1). public int Major { get; } + + /// The minor version number (e.g., 1 in PVE 8.1). public int Minor { get; } + /// Creates a new PVE version with the specified major and minor components. + /// The major version number. + /// The minor version number. public PveVersion(int major, int minor) { Major = major; @@ -34,11 +40,15 @@ namespace PSProxmoxVE.Core.Authentication return new PveVersion(major, minor); } + /// Returns true if this version is greater than or equal to the specified version. + /// The minimum major version. + /// The minimum minor version. public bool IsAtLeast(int major, int minor) { return Major > major || (Major == major && Minor >= minor); } + /// public override string ToString() => $"{Major}.{Minor}"; } } diff --git a/src/PSProxmoxVE.Core/Client/PveHttpClient.cs b/src/PSProxmoxVE.Core/Client/PveHttpClient.cs index 02c1600..36df156 100644 --- a/src/PSProxmoxVE.Core/Client/PveHttpClient.cs +++ b/src/PSProxmoxVE.Core/Client/PveHttpClient.cs @@ -30,6 +30,10 @@ namespace PSProxmoxVE.Core.Client private readonly HttpClient _httpClient; private bool _disposed; + /// + /// Creates an HTTP client authenticated with the specified PVE session. + /// + /// The authenticated PVE session providing credentials and base URL. public PveHttpClient(PveSession session) { _session = session ?? throw new ArgumentNullException(nameof(session)); @@ -394,6 +398,7 @@ namespace PSProxmoxVE.Core.Client return sb.ToString(); } + /// public void Dispose() { if (!_disposed) diff --git a/src/PSProxmoxVE.Core/Exceptions/PveApiException.cs b/src/PSProxmoxVE.Core/Exceptions/PveApiException.cs index 1d76a80..deaf0bc 100644 --- a/src/PSProxmoxVE.Core/Exceptions/PveApiException.cs +++ b/src/PSProxmoxVE.Core/Exceptions/PveApiException.cs @@ -3,13 +3,23 @@ using System.Net; namespace PSProxmoxVE.Core.Exceptions { - /// Exception thrown when the Proxmox VE API returns an error response + /// Exception thrown when the Proxmox VE API returns an error response. public class PveApiException : Exception { + /// The HTTP status code returned by the PVE API. public HttpStatusCode StatusCode { get; } + + /// The API resource path that was requested. public string Resource { get; } + + /// The HTTP method used for the request (GET, POST, PUT, DELETE). public string HttpMethod { get; } + /// Initializes a new instance for a failed PVE API request. + /// The HTTP status code returned. + /// The error message from the API. + /// The API resource path that was requested. + /// The HTTP method used. public PveApiException(HttpStatusCode statusCode, string message, string resource, string httpMethod) : base($"PVE API error ({(int)statusCode} {statusCode}) on {httpMethod} {resource}: {message}") { @@ -18,6 +28,12 @@ namespace PSProxmoxVE.Core.Exceptions HttpMethod = httpMethod; } + /// Initializes a new instance for a failed PVE API request, with an inner exception. + /// The HTTP status code returned. + /// The error message from the API. + /// The API resource path that was requested. + /// The HTTP method used. + /// The exception that caused this failure. public PveApiException(HttpStatusCode statusCode, string message, string resource, string httpMethod, Exception innerException) : base($"PVE API error ({(int)statusCode} {statusCode}) on {httpMethod} {resource}: {message}", innerException) { diff --git a/src/PSProxmoxVE.Core/Exceptions/PveAuthenticationException.cs b/src/PSProxmoxVE.Core/Exceptions/PveAuthenticationException.cs index 6d4112c..083b20f 100644 --- a/src/PSProxmoxVE.Core/Exceptions/PveAuthenticationException.cs +++ b/src/PSProxmoxVE.Core/Exceptions/PveAuthenticationException.cs @@ -2,14 +2,19 @@ using System; namespace PSProxmoxVE.Core.Exceptions { - /// Exception thrown when authentication to a Proxmox VE server fails + /// Exception thrown when authentication to a Proxmox VE server fails. public class PveAuthenticationException : Exception { + /// Initializes a new instance with the specified error message. + /// The error message describing the authentication failure. public PveAuthenticationException(string message) : base(message) { } + /// Initializes a new instance with the specified error message and inner exception. + /// The error message describing the authentication failure. + /// The exception that caused this failure. public PveAuthenticationException(string message, Exception innerException) : base(message, innerException) { diff --git a/src/PSProxmoxVE.Core/Exceptions/PveNotConnectedException.cs b/src/PSProxmoxVE.Core/Exceptions/PveNotConnectedException.cs index 296bedd..3dcbe71 100644 --- a/src/PSProxmoxVE.Core/Exceptions/PveNotConnectedException.cs +++ b/src/PSProxmoxVE.Core/Exceptions/PveNotConnectedException.cs @@ -2,14 +2,17 @@ using System; namespace PSProxmoxVE.Core.Exceptions { - /// Exception thrown when an operation is attempted without an active Proxmox VE session + /// Exception thrown when an operation is attempted without an active Proxmox VE session. public class PveNotConnectedException : Exception { + /// Initializes a new instance indicating no active session exists. public PveNotConnectedException() : base("No active Proxmox VE session. Run Connect-PveServer first.") { } + /// Initializes a new instance indicating no active session exists, with an inner exception. + /// The exception that caused this failure. public PveNotConnectedException(Exception innerException) : base("No active Proxmox VE session. Run Connect-PveServer first.", innerException) { diff --git a/src/PSProxmoxVE.Core/Exceptions/PveSessionExpiredException.cs b/src/PSProxmoxVE.Core/Exceptions/PveSessionExpiredException.cs index eb78e03..fb753e0 100644 --- a/src/PSProxmoxVE.Core/Exceptions/PveSessionExpiredException.cs +++ b/src/PSProxmoxVE.Core/Exceptions/PveSessionExpiredException.cs @@ -2,14 +2,17 @@ using System; namespace PSProxmoxVE.Core.Exceptions { - /// Exception thrown when the Proxmox VE session ticket has expired + /// Exception thrown when the Proxmox VE session ticket has expired. public class PveSessionExpiredException : Exception { + /// Initializes a new instance indicating the session has expired. public PveSessionExpiredException() : base("Your Proxmox VE session has expired. Please run Connect-PveServer to establish a new session.") { } + /// Initializes a new instance indicating the session has expired, with an inner exception. + /// The exception that caused this failure. public PveSessionExpiredException(Exception innerException) : base("Your Proxmox VE session has expired. Please run Connect-PveServer to establish a new session.", innerException) { diff --git a/src/PSProxmoxVE.Core/Exceptions/PveTaskFailedException.cs b/src/PSProxmoxVE.Core/Exceptions/PveTaskFailedException.cs index 0b99ffd..24d3917 100644 --- a/src/PSProxmoxVE.Core/Exceptions/PveTaskFailedException.cs +++ b/src/PSProxmoxVE.Core/Exceptions/PveTaskFailedException.cs @@ -2,12 +2,18 @@ using System; namespace PSProxmoxVE.Core.Exceptions { - /// Exception thrown when a Proxmox VE task completes with a failed exit status + /// Exception thrown when a Proxmox VE task completes with a failed exit status. public class PveTaskFailedException : Exception { + /// The UPID of the failed task. public string Upid { get; } + + /// The exit status string reported by the task (e.g., an error message). public string ExitStatus { get; } + /// Initializes a new instance for a task that failed with the specified exit status. + /// The UPID of the failed task. + /// The exit status string reported by the task. public PveTaskFailedException(string upid, string exitStatus) : base($"Task {upid} failed with exit status: {exitStatus}") { @@ -15,6 +21,10 @@ namespace PSProxmoxVE.Core.Exceptions ExitStatus = exitStatus; } + /// Initializes a new instance for a task that failed, with an inner exception. + /// The UPID of the failed task. + /// The exit status string reported by the task. + /// The exception that caused this failure. public PveTaskFailedException(string upid, string exitStatus, Exception innerException) : base($"Task {upid} failed with exit status: {exitStatus}", innerException) { diff --git a/src/PSProxmoxVE.Core/Exceptions/PveTaskTimeoutException.cs b/src/PSProxmoxVE.Core/Exceptions/PveTaskTimeoutException.cs index 3d5d725..b1091e6 100644 --- a/src/PSProxmoxVE.Core/Exceptions/PveTaskTimeoutException.cs +++ b/src/PSProxmoxVE.Core/Exceptions/PveTaskTimeoutException.cs @@ -2,12 +2,18 @@ using System; namespace PSProxmoxVE.Core.Exceptions { - /// Exception thrown when a Proxmox VE task does not complete within the allowed timeout period + /// Exception thrown when a Proxmox VE task does not complete within the allowed timeout period. public class PveTaskTimeoutException : Exception { + /// The UPID of the task that timed out. public string Upid { get; } + + /// The timeout duration that was exceeded. public TimeSpan Timeout { get; } + /// Initializes a new instance for a task that exceeded the specified timeout. + /// The UPID of the timed-out task. + /// The timeout duration that was exceeded. public PveTaskTimeoutException(string upid, TimeSpan timeout) : base($"Task {upid} did not complete within {timeout.TotalSeconds} seconds.") { @@ -15,6 +21,10 @@ namespace PSProxmoxVE.Core.Exceptions Timeout = timeout; } + /// Initializes a new instance for a task that exceeded the specified timeout, with an inner exception. + /// The UPID of the timed-out task. + /// The timeout duration that was exceeded. + /// The exception that caused this failure. public PveTaskTimeoutException(string upid, TimeSpan timeout, Exception innerException) : base($"Task {upid} did not complete within {timeout.TotalSeconds} seconds.", innerException) { diff --git a/src/PSProxmoxVE.Core/Exceptions/PveVersionException.cs b/src/PSProxmoxVE.Core/Exceptions/PveVersionException.cs index e2606a8..94c9a7d 100644 --- a/src/PSProxmoxVE.Core/Exceptions/PveVersionException.cs +++ b/src/PSProxmoxVE.Core/Exceptions/PveVersionException.cs @@ -3,13 +3,22 @@ using PSProxmoxVE.Core.Authentication; namespace PSProxmoxVE.Core.Exceptions { - /// Exception thrown when the connected Proxmox VE server does not meet the minimum version requirement for an operation + /// Exception thrown when the connected Proxmox VE server does not meet the minimum version requirement for an operation. public class PveVersionException : Exception { + /// The minimum required major version number. public int RequiredMajor { get; } + + /// The minimum required minor version number. public int RequiredMinor { get; } + + /// The actual server version that did not meet the requirement. public PveVersion ActualVersion { get; } + /// Initializes a new instance for a version requirement that was not met. + /// The minimum required major version. + /// The minimum required minor version. + /// The actual server version detected. public PveVersionException(int requiredMajor, int requiredMinor, PveVersion actualVersion) : base($"This operation requires Proxmox VE {requiredMajor}.{requiredMinor} or later. Connected server is version {actualVersion}.") { @@ -18,6 +27,11 @@ namespace PSProxmoxVE.Core.Exceptions ActualVersion = actualVersion; } + /// Initializes a new instance for a version requirement that was not met, with an inner exception. + /// The minimum required major version. + /// The minimum required minor version. + /// The actual server version detected. + /// The exception that caused this failure. public PveVersionException(int requiredMajor, int requiredMinor, PveVersion actualVersion, Exception innerException) : base($"This operation requires Proxmox VE {requiredMajor}.{requiredMinor} or later. Connected server is version {actualVersion}.", innerException) { diff --git a/src/PSProxmoxVE.Core/Models/Vms/PveCloudInitConfig.cs b/src/PSProxmoxVE.Core/Models/Vms/PveCloudInitConfig.cs index 63aa9ab..95826a7 100644 --- a/src/PSProxmoxVE.Core/Models/Vms/PveCloudInitConfig.cs +++ b/src/PSProxmoxVE.Core/Models/Vms/PveCloudInitConfig.cs @@ -48,6 +48,7 @@ namespace PSProxmoxVE.Core.Models.Vms [JsonProperty("cicustom")] public string? CiCustom { get; set; } + /// public override string ToString() => $"CloudInit: User={CiUser ?? "N/A"} | IP0={IpConfig0 ?? "N/A"} | NS={Nameserver ?? "N/A"}"; } diff --git a/src/PSProxmoxVE.Core/Models/Vms/PveGuestIpAddress.cs b/src/PSProxmoxVE.Core/Models/Vms/PveGuestIpAddress.cs index ce645d4..be0fc64 100644 --- a/src/PSProxmoxVE.Core/Models/Vms/PveGuestIpAddress.cs +++ b/src/PSProxmoxVE.Core/Models/Vms/PveGuestIpAddress.cs @@ -23,5 +23,6 @@ public class PveGuestIpAddress [JsonProperty("prefix")] public int Prefix { get; set; } + /// public override string ToString() => $"{Address}/{Prefix} ({Type})"; } diff --git a/src/PSProxmoxVE.Core/Models/Vms/PveGuestNetworkInterface.cs b/src/PSProxmoxVE.Core/Models/Vms/PveGuestNetworkInterface.cs index 63410e3..4060885 100644 --- a/src/PSProxmoxVE.Core/Models/Vms/PveGuestNetworkInterface.cs +++ b/src/PSProxmoxVE.Core/Models/Vms/PveGuestNetworkInterface.cs @@ -23,6 +23,7 @@ public class PveGuestNetworkInterface [JsonProperty("ip-addresses")] public PveGuestIpAddress[] IpAddresses { get; set; } = System.Array.Empty(); + /// public override string ToString() { var ips = IpAddresses.Length > 0 diff --git a/src/PSProxmoxVE.Core/Models/Vms/PveTaskLog.cs b/src/PSProxmoxVE.Core/Models/Vms/PveTaskLog.cs index 4158923..ab8b827 100644 --- a/src/PSProxmoxVE.Core/Models/Vms/PveTaskLog.cs +++ b/src/PSProxmoxVE.Core/Models/Vms/PveTaskLog.cs @@ -16,6 +16,7 @@ namespace PSProxmoxVE.Core.Models.Vms [JsonProperty("t")] public string Text { get; set; } = string.Empty; + /// public override string ToString() => $"{LineNumber,4}: {Text}"; } } diff --git a/src/PSProxmoxVE.Core/PSProxmoxVE.Core.csproj b/src/PSProxmoxVE.Core/PSProxmoxVE.Core.csproj index 5b444e8..6b52216 100644 --- a/src/PSProxmoxVE.Core/PSProxmoxVE.Core.csproj +++ b/src/PSProxmoxVE.Core/PSProxmoxVE.Core.csproj @@ -7,7 +7,7 @@ PSProxmoxVE.Core PSProxmoxVE.Core true - $(NoWarn);CS1591 + $(NoWarn)