JSHandle docs (#300)

Author: kblok

lib/PuppeteerSharp/ElementHandle.cs

@@ -83,7 +83,7 @@ public async Task<Stream> ScreenshotStreamAsync(ScreenshotOptions options)
         public async Task<byte[]> ScreenshotDataAsync(ScreenshotOptions options)
         {
             await ScrollIntoViewIfNeededAsync();
-            dynamic metrics = await _client.SendAsync("Page.getLayoutMetrics") as JObject;
+            dynamic metrics = await Client.SendAsync("Page.getLayoutMetrics") as JObject;
 
             var boundingBox = await BoundingBoxAsync();
             if (boundingBox == null)
@@ -129,7 +129,7 @@ public async Task UploadFileAsync(params string[] filePaths)
         {
             var files = filePaths.Select(Path.GetFullPath).ToArray();
             var objectId = RemoteObject.objectId.ToString();
-            await _client.SendAsync("DOM.setFileInputFiles", new { objectId, files });
+            await Client.SendAsync("DOM.setFileInputFiles", new { objectId, files });
         }
 
         /// <summary>
@@ -297,14 +297,14 @@ public async Task<BoundingBox> BoundingBoxAsync()
 
             try
             {
-                result = await _client.SendAsync("DOM.getBoxModel", new
+                result = await Client.SendAsync("DOM.getBoxModel", new
                 {
                     objectId = RemoteObject.objectId.ToString()
                 });
             }
             catch (PuppeteerException ex)
             {
-                _logger.LogError(ex.Message);
+                Logger.LogError(ex.Message);
             }
 
             if (result == null)

lib/PuppeteerSharp/JSHandle.cs

@@ -7,23 +7,44 @@
 
 namespace PuppeteerSharp
 {
+    /// <summary>
+    /// JSHandle represents an in-page JavaScript object. JSHandles can be created with the <see cref="Page.EvaluateExpressionHandleAsync(string)"/> and <see cref="Page.EvaluateFunctionHandleAsync(string, object[])"/> methods.
+    /// </summary>
     public class JSHandle
     {
-        private ExecutionContext _context;
-        protected readonly Session _client;
-        protected readonly ILogger _logger;
-
-        public JSHandle(ExecutionContext context, Session client, object remoteObject)
+        internal JSHandle(ExecutionContext context, Session client, object remoteObject)
         {
-            _context = context;
-            _client = client;
-            _logger = _client.Connection.LoggerFactory.CreateLogger(this.GetType());
+            ExecutionContext = context;
+            Client = client;
+            Logger = Client.Connection.LoggerFactory.CreateLogger(this.GetType());
             RemoteObject = remoteObject;
         }
 
-        public ExecutionContext ExecutionContext => _context;
-        public bool Disposed { get; set; }
-        public dynamic RemoteObject { get; internal set; }
+        /// <summary>
+        /// Gets the execution context.
+        /// </summary>
+        /// <value>The execution context.</value>
+        public ExecutionContext ExecutionContext { get; }
+        /// <summary>
+        /// Gets or sets a value indicating whether this <see cref="PuppeteerSharp.JSHandle"/> is disposed.
+        /// </summary>
+        /// <value><c>true</c> if disposed; otherwise, <c>false</c>.</value>
+        public bool Disposed { get; private set; }
+        /// <summary>
+        /// Gets or sets the remote object.
+        /// </summary>
+        /// <value>The remote object.</value>
+        public dynamic RemoteObject { get; }
+        /// <summary>
+        /// Gets the client.
+        /// </summary>
+        /// <value>The client.</value>
+        protected Session Client { get; }
+        /// <summary>
+        /// Gets the logger.
+        /// </summary>
+        /// <value>The logger.</value>
+        protected ILogger Logger { get; }
 
         /// <summary>
         /// Fetches a single property from the referenced object
@@ -58,7 +79,7 @@ public async Task<JSHandle> GetPropertyAsync(string propertyName)
         /// </example>
         public async Task<Dictionary<string, JSHandle>> GetPropertiesAsync()
         {
-            var response = await _client.SendAsync("Runtime.getProperties", new
+            var response = await Client.SendAsync("Runtime.getProperties", new
             {
                 objectId = RemoteObject.objectId.ToString(),
                 ownProperties = true
@@ -67,8 +88,11 @@ public async Task<Dictionary<string, JSHandle>> GetPropertiesAsync()
             foreach (var property in response.result)
             {
                 if (property.enumerable == null)
+                {
                     continue;
-                result.Add(property.name.ToString(), _context.ObjectHandleFactory(property.value));
+                }
+
+                result.Add(property.name.ToString(), ExecutionContext.ObjectHandleFactory(property.value));
             }
             return result;
         }
@@ -94,19 +118,23 @@ public async Task<T> JsonValueAsync<T>()
         {
             if (RemoteObject.objectId != null)
             {
-                dynamic response = await _client.SendAsync("Runtime.callFunctionOn", new Dictionary<string, object>()
+                dynamic response = await Client.SendAsync("Runtime.callFunctionOn", new Dictionary<string, object>
                 {
-                    {"functionDeclaration", "function() { return this; }"},
-                    {"objectId", RemoteObject.objectId},
-                    {"returnByValue", true},
-                    {"awaitPromise", true}
+                    ["functionDeclaration"] = "function() { return this; }",
+                    ["objectId"] = RemoteObject.objectId,
+                    ["returnByValue"] = true,
+                    ["awaitPromise"] = true
                 });
                 return (T)RemoteObjectHelper.ValueFromRemoteObject<T>(response.result);
             }
 
             return (T)RemoteObjectHelper.ValueFromRemoteObject<T>(RemoteObject);
         }
 
+        /// <summary>
+        /// Disposes the Handle. It will mark the JSHandle as disposed and release the <see cref="JSHandle.RemoteObject"/>
+        /// </summary>
+        /// <returns>The async.</returns>
         public async Task DisposeAsync()
         {
             if (Disposed)
@@ -115,9 +143,10 @@ public async Task DisposeAsync()
             }
 
             Disposed = true;
-            await RemoteObjectHelper.ReleaseObject(_client, RemoteObject, _logger);
+            await RemoteObjectHelper.ReleaseObject(Client, RemoteObject, Logger);
         }
 
+        /// <inheritdoc/>
         public override string ToString()
         {
             if (((JObject)RemoteObject)["objectId"] != null)
@@ -132,13 +161,25 @@ public override string ToString()
         internal object FormatArgument(ExecutionContext context)
         {
             if (ExecutionContext != context)
+            {
                 throw new PuppeteerException("JSHandles can be evaluated only in the context they were created!");
+            }
+
             if (Disposed)
+            {
                 throw new PuppeteerException("JSHandle is disposed!");
+            }
+
             if (RemoteObject.unserializableValue != null)
+            {
                 return new { RemoteObject.unserializableValue };
+            }
+
             if (RemoteObject.objectId == null)
+            {
                 return new { RemoteObject.value };
+            }
+
             return new { RemoteObject.objectId };
         }
     }

lib/PuppeteerSharp/Page.cs

@@ -58,7 +58,7 @@ private Page(Session client, Target target, FrameTree frameTree, bool ignoreHTTP
             Touchscreen = new Touchscreen(client, Keyboard);
             Tracing = new Tracing(client);
             Coverage = new Coverage(client);
-            
+
             _frameManager = new FrameManager(client, frameTree, this);
             _networkManager = new NetworkManager(client, _frameManager);
             _emulationManager = new EmulationManager(client);
@@ -1525,7 +1525,7 @@ private async Task OnCertificateError(MessageEventArgs e)
                         {"action", "continue"}
                     });
                 }
-                catch(PuppeteerException ex)
+                catch (PuppeteerException ex)
                 {
                     _logger.LogError(ex.ToString());
                 }

lib/PuppeteerSharp/Session.cs

@@ -27,7 +27,7 @@ public Session(Connection connection, string targetId, string sessionId)
 
         #region Properties
         public string TargetId { get; }
-        public string SessionId { get; private set; }
+        public string SessionId { get; }
         public Connection Connection { get; private set; }
         public event EventHandler<MessageEventArgs> MessageReceived;
         public event EventHandler<TracingCompleteEventArgs> TracingComplete;

lib/PuppeteerSharp/TargetInfo.cs

@@ -18,6 +18,6 @@ public TargetInfo(dynamic targetInfo)
         public string Type { get; internal set; }
         public string Url { get; internal set; }
         public string TargetId { get; internal set; }
-        public dynamic SourceObject { get; private set; }
+        public dynamic SourceObject { get; }
     }
 }