Initial version of low allocation and low overhead SshCommandLite class

Author: Levi--G

src/Renci.SshNet/Common/CommandExitedEventArgs.cs

@@ -0,0 +1,46 @@
+#nullable enable
+using System;
+
+namespace Renci.SshNet.Common
+{
+    /// <summary>
+    /// Class for command exit related events.
+    /// </summary>
+    public class CommandExitedEventArgs : EventArgs
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CommandExitedEventArgs"/> class.
+        /// </summary>
+        /// <param name="exitStatus">The exit status.</param>
+        /// <param name="exitSignal">The exit signal.</param>
+        public CommandExitedEventArgs(int? exitStatus, string? exitSignal)
+        {
+            ExitStatus = exitStatus;
+            ExitSignal = exitSignal;
+        }
+
+        /// <summary>
+        /// Gets the number representing the exit status of the command, if applicable,
+        /// otherwise <see langword="null"/>.
+        /// </summary>
+        /// <remarks>
+        /// The value is not <see langword="null"/> when an exit status code has been returned
+        /// from the server. If the command terminated due to a signal, <see cref="ExitSignal"/>
+        /// may be not <see langword="null"/> instead.
+        /// </remarks>
+        /// <seealso cref="ExitSignal"/>
+        public int? ExitStatus { get; }
+
+
+        /// <summary>
+        /// Gets the name of the signal due to which the command
+        /// terminated violently, if applicable, otherwise <see langword="null"/>.
+        /// </summary>
+        /// <remarks>
+        /// The value (if it exists) is supplied by the server and is usually one of the
+        /// following, as described in https://datatracker.ietf.org/doc/html/rfc4254#section-6.10:
+        /// ABRT, ALRM, FPE, HUP, ILL, INT, KILL, PIPE, QUIT, SEGV, TER, USR1, USR2.
+        /// </remarks>
+        public string? ExitSignal { get; }
+    }
+}

src/Renci.SshNet/Common/CommandOutputEventArgs.cs

@@ -0,0 +1,44 @@
+#nullable enable
+using System;
+using System.Text;
+
+namespace Renci.SshNet.Common
+{
+    /// <summary>
+    /// Base class for command output related events.
+    /// </summary>
+    public class CommandOutputEventArgs : EventArgs
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CommandOutputEventArgs"/> class.
+        /// </summary>
+        /// <param name="rawData">The raw data received.</param>
+        /// <param name="encoding">The encoding used for the transmission.</param>
+        public CommandOutputEventArgs(ArraySegment<byte> rawData, Encoding encoding)
+        {
+            RawData = rawData;
+            Encoding = encoding;
+        }
+
+        /// <summary>
+        /// Gets the received data as <see langword="string"/>.
+        /// </summary>
+        public string Text
+        {
+            get
+            {
+                return Encoding.GetString(RawData.Array, RawData.Offset, RawData.Count);
+            }
+        }
+
+        /// <summary>
+        /// Gets the raw data received from the server. This is the data that was used to create the <see cref="Text"/> property.
+        /// </summary>
+        public ArraySegment<byte> RawData { get; }
+
+        /// <summary>
+        /// Gets the output encoding used.
+        /// </summary>
+        public Encoding Encoding { get; }
+    }
+}

src/Renci.SshNet/Common/ExtendedCommandEventArgs.cs

@@ -0,0 +1,40 @@
+using System;
+#nullable enable
+using System.Text;
+
+namespace Renci.SshNet.Common
+{
+    /// <summary>
+    /// Class for extended text output related events.
+    /// </summary>
+    public class ExtendedCommandEventArgs : CommandOutputEventArgs
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ExtendedCommandEventArgs"/> class.
+        /// </summary>
+        /// <param name="rawData">The raw data received.</param>
+        /// <param name="encoding">The encoding used for the transmission.</param>
+        /// <param name="dataTypeCode">The data type code.</param>
+        public ExtendedCommandEventArgs(ArraySegment<byte> rawData, Encoding encoding, uint dataTypeCode)
+            : base(rawData, encoding)
+        {
+            DataTypeCode = dataTypeCode;
+        }
+
+        /// <summary>
+        /// Gets the data type code.
+        /// </summary>
+        public uint DataTypeCode { get; }
+
+        /// <summary>
+        /// Gets a value indicating whether the current data represents an stderr output.
+        /// </summary>
+        public bool IsError
+        {
+            get
+            {
+                return DataTypeCode == 1;
+            }
+        }
+    }
+}

src/Renci.SshNet/ISshClient.cs

@@ -66,6 +66,38 @@ public interface ISshClient : IBaseClient
         /// <exception cref="ArgumentNullException"><paramref name="commandText"/> is <see langword="null"/>.</exception>
         public SshCommand RunCommand(string commandText);
 
+        /// <summary>
+        /// Creates the command to be executed.
+        /// </summary>
+        /// <param name="commandText">The command text.</param>
+        /// <returns><see cref="SshCommandLite"/> object.</returns>
+        /// <exception cref="SshConnectionException">Client is not connected.</exception>
+        public SshCommandLite CreateCommandLite(string commandText);
+
+        /// <summary>
+        /// Creates the command to be executed with specified encoding.
+        /// </summary>
+        /// <param name="commandText">The command text.</param>
+        /// <param name="encoding">The encoding to use for results.</param>
+        /// <returns><see cref="SshCommandLite"/> object which uses specified encoding.</returns>
+        /// <remarks>This method will change current default encoding.</remarks>
+        /// <exception cref="SshConnectionException">Client is not connected.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="commandText"/> or <paramref name="encoding"/> is <see langword="null"/>.</exception>
+        public SshCommandLite CreateCommandLite(string commandText, Encoding encoding);
+
+        /// <summary>
+        /// Creates and executes the command.
+        /// </summary>
+        /// <param name="commandText">The command text.</param>
+        /// <returns>Returns an instance of <see cref="SshCommandLite"/> with execution results.</returns>
+        /// <remarks>This method internally uses asynchronous calls.</remarks>
+        /// <exception cref="ArgumentException">CommandText property is empty.</exception>
+        /// <exception cref="SshException">Invalid Operation - An existing channel was used to execute this command.</exception>
+        /// <exception cref="InvalidOperationException">Asynchronous operation is already in progress.</exception>
+        /// <exception cref="SshConnectionException">Client is not connected.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="commandText"/> is <see langword="null"/>.</exception>
+        public SshCommandLite RunCommandLite(string commandText);
+
         /// <summary>
         /// Creates the shell.
         /// </summary>

src/Renci.SshNet/SshClient.cs

@@ -209,6 +209,29 @@ public SshCommand RunCommand(string commandText)
             return cmd;
         }
 
+        /// <inheritdoc />
+        public SshCommandLite CreateCommandLite(string commandText)
+        {
+            return CreateCommandLite(commandText, ConnectionInfo.Encoding);
+        }
+
+        /// <inheritdoc />
+        public SshCommandLite CreateCommandLite(string commandText, Encoding encoding)
+        {
+            EnsureSessionIsOpen();
+
+            ConnectionInfo.Encoding = encoding;
+            return new SshCommandLite(Session!, commandText, encoding);
+        }
+
+        /// <inheritdoc />
+        public SshCommandLite RunCommandLite(string commandText)
+        {
+            var cmd = CreateCommandLite(commandText);
+            _ = cmd.Execute();
+            return cmd;
+        }
+
         /// <inheritdoc />
         public Shell CreateShell(Stream input, Stream output, Stream extendedOutput, string terminalName, uint columns, uint rows, uint width, uint height, IDictionary<TerminalModes, uint>? terminalModes, int bufferSize)
         {