adding documentation for the public interfaces

adstep · Dec 15, 2022 · 261715c · 261715c
1 parent 31a7da7
commit 261715c
Show file tree

Hide file tree

Showing 13 changed files with 184 additions and 64 deletions.
diff --git a/src/WinRMSharp.Examples/Example.Protocol/Program.cs b/src/WinRMSharp.Examples/Example.Protocol/Program.cs
@@ -31,10 +31,10 @@ static async Task Main(string[] args)
         Console.WriteLine($"Stdout: \r\n{commandState.Stdout}");
         Console.WriteLine($"Stderr: \r\n{commandState.Stderr}");
 
-        await protocol.CleanupCommand(shellId, commandId);
+        await protocol.CloseCommand(shellId, commandId);
         try
         {
-            await protocol.CleanupCommand("11111111-1111-1111-1111-111111111111", commandId);
+            await protocol.CloseCommand("11111111-1111-1111-1111-111111111111", commandId);
         }
         catch { }
         await protocol.CloseShell(shellId);

diff --git a/src/WinRMSharp.IntegrationTests/ProtocolTests.cs b/src/WinRMSharp.IntegrationTests/ProtocolTests.cs
@@ -40,7 +40,7 @@ public async Task RunCommandWithArgsAndCleanup()
             string shellId = await _protocol.OpenShell();
             string commandId = await _protocol.RunCommand(shellId, "ipconfig", new string[] { "/all" });
 
-            await _protocol.CleanupCommand(shellId, commandId);
+            await _protocol.CloseCommand(shellId, commandId);
             await _protocol.CloseShell(shellId);
 
             Assert.Matches(@"^\w{8}-\w{4}-\w{4}-\w{4}-\w{12}$", commandId);
@@ -52,7 +52,7 @@ public async Task RunCommandWithoutArgsAndCleanup()
             string shellId = await _protocol.OpenShell();
             string commandId = await _protocol.RunCommand(shellId, "hostname");
 
-            await _protocol.CleanupCommand(shellId, commandId);
+            await _protocol.CloseCommand(shellId, commandId);
             await _protocol.CloseShell(shellId);
 
             Assert.Matches(@"^\w{8}-\w{4}-\w{4}-\w{4}-\w{12}$", commandId);
@@ -72,7 +72,7 @@ public async Task RunCommandWithEnv()
 
             CommandState state = await _protocol.PollCommandState(shellId, commandId);
 
-            await _protocol.CleanupCommand(shellId, commandId);
+            await _protocol.CloseCommand(shellId, commandId);
             await _protocol.CloseShell(shellId);
 
             Assert.Matches(@"hi mom another var", state.Stdout);
@@ -86,7 +86,7 @@ public async Task GetCommandState()
 
             CommandState state = await _protocol.PollCommandState(shellId, commandId);
 
-            await _protocol.CleanupCommand(shellId, commandId);
+            await _protocol.CloseCommand(shellId, commandId);
             await _protocol.CloseShell(shellId);
 
             Assert.Equal(0, state.StatusCode);
@@ -102,11 +102,11 @@ public async Task RunCommandExceedingOperationTimeout()
 
             CommandState state = await _protocol.PollCommandState(shellId, commandId);
 
-            await _protocol.CleanupCommand(shellId, commandId);
+            await _protocol.CloseCommand(shellId, commandId);
             await _protocol.CloseShell(shellId);
 
             Assert.Equal(0, state.StatusCode);
             Assert.Equal(0, state.Stderr.Length);
         }
     }
-}
+}
diff --git a/src/WinRMSharp.Tests/ProtocolTests.cs b/src/WinRMSharp.Tests/ProtocolTests.cs
@@ -27,7 +27,7 @@ public async Task RunCommandWithArgsAndCleanup()
             string shellId = await protocol.OpenShell();
             string commandId = await protocol.RunCommand(shellId, "ipconfig", new[] { "/all" });
 
-            await protocol.CleanupCommand(shellId, commandId);
+            await protocol.CloseCommand(shellId, commandId);
             await protocol.CloseShell(shellId);
 
             Assert.Equal("11111111-1111-1111-1111-111111111114", commandId);
@@ -42,7 +42,7 @@ public async Task RunCommandWithoutArgsAndCleanup()
             string shellId = await protocol.OpenShell();
             string commandId = await protocol.RunCommand(shellId, "hostname");
 
-            await protocol.CleanupCommand(shellId, commandId);
+            await protocol.CloseCommand(shellId, commandId);
             await protocol.CloseShell(shellId);
 
             Assert.Equal("11111111-1111-1111-1111-111111111114", commandId);
@@ -58,7 +58,7 @@ public async Task GetCommandState()
             string commandId = await protocol.RunCommand(shellId, "ipconfig", new[] { "/all" });
             CommandState commandState = await protocol.GetCommandState(shellId, commandId);
 
-            await protocol.CleanupCommand(shellId, commandId);
+            await protocol.CloseCommand(shellId, commandId);
             await protocol.CloseShell(shellId);
 
             Assert.NotNull(commandState);
@@ -77,7 +77,7 @@ public async Task PollCommandState()
             string commandId = await protocol.RunCommand(shellId, "ipconfig", new[] { "/all" });
             CommandState commandState = await protocol.PollCommandState(shellId, commandId);
 
-            await protocol.CleanupCommand(shellId, commandId);
+            await protocol.CloseCommand(shellId, commandId);
             await protocol.CloseShell(shellId);
 
             Assert.NotNull(commandState);
@@ -97,7 +97,7 @@ public async Task SendCommandInput()
             await protocol.SendCommandInput(shellId, commandId, "echo \"hello world\" && exit\\r\\n");
             CommandState commandState = await protocol.GetCommandState(shellId, commandId);
 
-            await protocol.CleanupCommand(shellId, commandId);
+            await protocol.CloseCommand(shellId, commandId);
             await protocol.CloseShell(shellId);
 
             Assert.NotNull(commandState);
@@ -126,7 +126,7 @@ public async Task RunCommandExceedingOperationTimeout()
 
             CommandState state = await protocol.PollCommandState(shellId, commandId);
 
-            await protocol.CleanupCommand(shellId, commandId);
+            await protocol.CloseCommand(shellId, commandId);
             await protocol.CloseShell(shellId);
 
             Assert.Equal(0, state.StatusCode);
@@ -140,7 +140,7 @@ public async Task HandleCleanupCommandFault()
             MockClient mockClient = new MockClient();
             Protocol protocol = new Protocol(mockClient.Transport.Object, mockClient.GuidProvider.Object);
 
-            await protocol.CleanupCommand("11111111-1111-1111-1111-111111111113", "11111111-1111-1111-1111-111111111117");
+            await protocol.CloseCommand("11111111-1111-1111-1111-111111111113", "11111111-1111-1111-1111-111111111117");
 
             // We've setup the transport to return a failure and we're just checcking an exception doesn't bubble up
         }

diff --git a/src/WinRMSharp.Tests/WinRMClientTests.cs b/src/WinRMSharp.Tests/WinRMClientTests.cs
@@ -7,7 +7,7 @@ namespace WinRMSharp.Tests
     public class WinRMClientTests
     {
         [Fact]
-        public void VerifyConstruciton()
+        public void VerifyConstruction()
         {
             string baseUrl = "https://localhost:5986";
             ICredentials credentials = new NetworkCredential()
@@ -18,7 +18,6 @@ public void VerifyConstruciton()
             };
             WinRMClientOptions clientOptions = new WinRMClientOptions()
             {
-                Locale = "en-US",
                 MaxEnvelopeSize = 1,
                 OperationTimeout = TimeSpan.FromSeconds(20),
                 ReadTimeout = TimeSpan.FromSeconds(30)

diff --git a/src/WinRMSharp/Exceptions/OperationTimeoutException.cs b/src/WinRMSharp/Exceptions/OperationTimeoutException.cs
@@ -1,6 +1,6 @@
 namespace WinRMSharp.Exceptions
 {
-    internal class OperationTimeoutException : Exception
+    internal class OperationTimeoutException : WinRMException
     {
         public OperationTimeoutException()
         {

diff --git a/src/WinRMSharp/Exceptions/TransportException.cs b/src/WinRMSharp/Exceptions/TransportException.cs
@@ -1,8 +1,18 @@
 namespace WinRMSharp.Exceptions
 {
+    /// <summary>
+    /// Wraps WinRM transport errors (unexpected HTTP error codes, etc). 
+    /// </summary>
     public class TransportException : WinRMException
     {
+        /// <summary>
+        /// Http status code of response.
+        /// </summary>
         public int Code { get; set; } = 500;
+
+        /// <summary>
+        /// Content of response message.
+        /// </summary>
         public string? Content { get; set; }
 
         public TransportException(int code, string content)

diff --git a/src/WinRMSharp/Exceptions/WSManFaultException.cs b/src/WinRMSharp/Exceptions/WSManFaultException.cs
@@ -1,5 +1,8 @@
 namespace WinRMSharp.Exceptions
 {
+    /// <summary>
+    /// Wraps error information returned as part of a response with a WSManFualt (see https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-wsmv/2b6ab0b1-4d5c-4c13-9f28-0f04716e5fa4).
+    /// </summary>
     internal class WSManFaultException : WinRMException
     {
         public string? FaultCode { get; set; }

diff --git a/src/WinRMSharp/Exceptions/WinRMException.cs b/src/WinRMSharp/Exceptions/WinRMException.cs
@@ -1,5 +1,8 @@
 namespace WinRMSharp.Exceptions
 {
+    /// <summary>
+    /// Base exeception for encapsulating all WinRM exceptions.
+    /// </summary>
     public class WinRMException : Exception
     {
         public WinRMException()

diff --git a/src/WinRMSharp/IProtocol.cs b/src/WinRMSharp/IProtocol.cs
@@ -1,15 +1,71 @@
 namespace WinRMSharp
 {
+    /// <summary>
+    /// Encapsulates WinRM network protocol for sending/receiving SOAP requests/responses necessary
+    /// for executing remote commands.
+    /// </summary>
     public interface IProtocol
     {
+        /// <summary>
+        /// Network transport used for sending/receiving SOAP requests/responses.
+        /// </summary>
         ITransport Transport { get; }
 
+        /// <summary>
+        /// Open a shell instance on the destination host.
+        /// </summary>
+        /// <param name="inputStream">Input streams to open.</param>
+        /// <param name="outputStream">Output streams to open.</param>
+        /// <param name="workingDirectory">Working directory of shell.</param>
+        /// <param name="envVars">Environment variables of shell.</param>
+        /// <param name="idleTimeout">Time length before shell is closed, if unused.</param>
+        /// <returns>Identifier for opened shell.</returns>
         Task<string> OpenShell(string inputStream = "stdin", string outputStream = "stdout stderr", string? workingDirectory = null, Dictionary<string, string>? envVars = null, TimeSpan? idleTimeout = null);
+
+        /// <summary>
+        /// Run a command in an opened shell on the destination host.
+        /// </summary>
+        /// <param name="shellId">The shell id on the remote machine. See <see cref="OpenShell"/>.</param>
+        /// <param name="command">The command id on the remote machine. See <see cref="RunCommand"/>.</param>
+        /// <param name="args">Array of arguments for the command.</param>
+        /// <returns>Identifier for the executing command.</returns>
         Task<string> RunCommand(string shellId, string command, string[]? args = null);
+
+        /// <summary>
+        /// Send input to a command executing in a shell.
+        /// </summary>
+        /// <param name="shellId">The shell id on the remote machine. See <see cref="OpenShell"/>.</param>
+        /// <param name="command">The command id on the remote machine. See <see cref="RunCommand"/>.</param>
+        /// <param name="input">Input text to send.</param>
+        /// <param name="end">Boolean flag to indicate to close the stdin stream.</param>
         Task SendCommandInput(string shellId, string commandId, string input, bool end = false);
+
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="shellId">The shell id on the remote machine. See <see cref="OpenShell"/>.</param>
+        /// <param name="command">The command id on the remote machine. See <see cref="RunCommand"/>.</param>
         Task<CommandState> PollCommandState(string shellId, string commandId);
+
+        /// <summary>
+        /// Gets the latest state of a command executing in a shell.
+        /// </summary>
+        /// <param name="shellId">The shell id on the remote machine. See <see cref="OpenShell"/>.</param>
+        /// <param name="command">The command id on the remote machine. See <see cref="RunCommand"/>.</param>
+        /// <returns>State of a executing command.</returns>
         Task<CommandState> GetCommandState(string shellId, string commandId);
+
+        /// <summary>
+        /// Cleans up an executed command on the destination host.
+        /// </summary>
+        /// <param name="shellId">The shell id on the remote machine. See <see cref="OpenShell"/>.</param>
+        /// <param name="command">The command id on the remote machine. See <see cref="RunCommand"/>.</param>
+        Task CloseCommand(string shellId, string commandId);
+
+        /// <summary>
+        /// Close a shell on the destination host.
+        /// </summary>
+        /// <param name="shellId">The shell id on the remote machine. See <see cref="OpenShell"/>.</param>
         Task CloseShell(string shellId);
-        Task CleanupCommand(string shellId, string commandId);
     }
 }
diff --git a/src/WinRMSharp/ITransport.cs b/src/WinRMSharp/ITransport.cs
@@ -1,7 +1,18 @@
 namespace WinRMSharp
 {
+    /// <summary>
+    /// Encapsulates network transport for sending/receiving SOAP requests/responses
+    /// over WinRM.
+    /// </summary>
     public interface ITransport
     {
+        /// <summary>
+        /// Sends an XML message to the destination host.
+        /// </summary>
+        /// <param name="message">XML request message to send</param>
+        /// <returns>XML response message</returns>
+        /// <exception cref="InvalidCredentialException">Thrown when provided credentials are invalid.</exception>
+        /// <exception cref="TransportException">Thrown when response returns non success status code [200,299).</exception>
         Task<string> Send(string message);
     }
 }