CDPSession docs (#292)

Author: kblok

lib/PuppeteerSharp.Tests/PuppeteerBaseTest.cs

@@ -33,7 +33,7 @@ protected void Initialize()
             HttpsServer.Reset();
         }
 
-        protected static Task<dynamic> WaitForEvents(Session emitter, string eventName, int eventCount = 1)
+        protected static Task<dynamic> WaitForEvents(CDPSession emitter, string eventName, int eventCount = 1)
         {
             var completion = new TaskCompletionSource<dynamic>();
             void handler(object sender, MessageEventArgs e)

lib/PuppeteerSharp.Tests/TargetTests/CreateCDPSessionTests.cs

@@ -18,7 +18,7 @@ public CreateCDPSessionTests(ITestOutputHelper output) : base(output)
         [Fact]
         public async Task ShouldWork()
         {
-            var client = await Page.Target.CreateCDPSession();
+            var client = await Page.Target.CreateCDPSessionAsync();
 
             await Task.WhenAll(
               client.SendAsync("Runtime.enable"),
@@ -31,7 +31,7 @@ await Task.WhenAll(
         [Fact]
         public async Task ShouldSendEvents()
         {
-            var client = await Page.Target.CreateCDPSession();
+            var client = await Page.Target.CreateCDPSessionAsync();
             await client.SendAsync("Network.enable");
             var events = new List<object>();
 
@@ -50,7 +50,7 @@ public async Task ShouldSendEvents()
         [Fact]
         public async Task ShouldEnableAndDisableDomainsIndependently()
         {
-            var client = await Page.Target.CreateCDPSession();
+            var client = await Page.Target.CreateCDPSessionAsync();
             await client.SendAsync("Runtime.enable");
             await client.SendAsync("Debugger.enable");
             // JS coverage enables and then disables Debugger domain.
@@ -69,7 +69,7 @@ await Task.WhenAll(
         [Fact]
         public async Task ShouldBeAbleToDetachSession()
         {
-            var client = await Page.Target.CreateCDPSession();
+            var client = await Page.Target.CreateCDPSessionAsync();
             await client.SendAsync("Runtime.enable");
             var evalResponse = await client.SendAsync("Runtime.evaluate", new { expression = "1 + 2", returnByValue = true });
             Assert.Equal(3, evalResponse.result.value.ToObject<int>());

lib/PuppeteerSharp/Session.cs renamed to lib/PuppeteerSharp/CDPSession.cs

@@ -7,54 +7,103 @@
 
 namespace PuppeteerSharp
 {
-    public class Session : IDisposable
+    /// <summary>
+    /// The CDPSession instances are used to talk raw Chrome Devtools Protocol:
+    ///  * Protocol methods can be called with <see cref="CDPSession.SendAsync(string, bool, dynamic)"/> method.
+    ///  * Protocol events, using the <see cref="CDPSession.MessageReceived"/> event.
+    /// 
+    /// Documentation on DevTools Protocol can be found here: <see href="https://chromedevtools.github.io/devtools-protocol/"/>.
+    /// 
+    /// <code>
+    /// <![CDATA[
+    /// var client = await Page.Target.CreateCDPSessionAsync();
+    /// await client.SendAsync("Animation.enable");
+    /// client.MessageReceived += (sender, e) =>
+    /// {
+    ///      if (e.MessageID == "Animation.animationCreated")
+    ///      {
+    ///          Console.WriteLine("Animation created!");
+    ///      }
+    /// };
+    /// dynamic response = await client.SendAsync("Animation.getPlaybackRate");
+    /// Console.WriteLine("playback rate is " + response.playbackRate);
+    /// await client.SendAsync("Animation.setPlaybackRate", new
+    /// {
+    ///     playbackRate = Convert.ToInt32(response.playbackRate / 2)
+    /// });
+    /// ]]></code>
+    /// </summary>
+    public class CDPSession : IDisposable
     {
-        public Session(Connection connection, string targetId, string sessionId)
+        internal CDPSession(Connection connection, string targetId, string sessionId)
         {
             Connection = connection;
             TargetId = targetId;
             SessionId = sessionId;
 
             _callbacks = new Dictionary<int, MessageTask>();
-            _logger = Connection.LoggerFactory.CreateLogger<Session>();
+            _logger = Connection.LoggerFactory.CreateLogger<CDPSession>();
         }
 
         #region Private Members
-        private int _lastId = 0;
+        private int _lastId;
         private readonly Dictionary<int, MessageTask> _callbacks;
         private readonly ILogger _logger;
         #endregion
 
         #region Properties
+        /// <summary>
+        /// Gets the target identifier.
+        /// </summary>
+        /// <value>The target identifier.</value>
         public string TargetId { get; }
+        /// <summary>
+        /// Gets the session identifier.
+        /// </summary>
+        /// <value>The session identifier.</value>
         public string SessionId { get; }
+        /// <summary>
+        /// Gets the connection.
+        /// </summary>
+        /// <value>The connection.</value>
         public Connection Connection { get; private set; }
+        /// <summary>
+        /// Occurs when message received from Chromium.
+        /// </summary>
         public event EventHandler<MessageEventArgs> MessageReceived;
+        /// <summary>
+        /// Occurs when tracing is completed.
+        /// </summary>
         public event EventHandler<TracingCompleteEventArgs> TracingComplete;
+        /// <summary>
+        /// Gets or sets a value indicating whether this <see cref="T:PuppeteerSharp.CDPSession"/> is closed.
+        /// </summary>
+        /// <value><c>true</c> if is closed; otherwise, <c>false</c>.</value>
         public bool IsClosed { get; internal set; }
         #endregion
 
         #region Public Methods
 
-        public async Task<T> SendAsync<T>(string method, dynamic args = null)
+        internal async Task<T> SendAsync<T>(string method, dynamic args = null)
         {
             var content = await SendAsync(method, true, args);
             return JsonConvert.DeserializeObject<T>(content);
         }
 
-        public Task<dynamic> SendAsync(string method, dynamic args = null)
+        internal Task<dynamic> SendAsync(string method, dynamic args = null)
         {
             return SendAsync(method, false, args ?? new { });
         }
 
-        public async Task<dynamic> SendAsync(string method, bool rawContent, dynamic args = null)
+        internal async Task<dynamic> SendAsync(string method, bool rawContent, dynamic args = null)
         {
             if (Connection == null)
             {
                 throw new Exception($"Protocol error ({method}): Session closed. Most likely the page has been closed.");
             }
             int id = ++_lastId;
-            var message = JsonConvert.SerializeObject(new Dictionary<string, object>(){
+            var message = JsonConvert.SerializeObject(new Dictionary<string, object>
+            {
                 {"id", id},
                 {"method", method},
                 {"params", args}
@@ -72,7 +121,8 @@ public async Task<dynamic> SendAsync(string method, bool rawContent, dynamic arg
 
             try
             {
-                await Connection.SendAsync("Target.sendMessageToTarget", new Dictionary<string, object>() {
+                await Connection.SendAsync("Target.sendMessageToTarget", new Dictionary<string, object>
+                {
                     {"sessionId", SessionId},
                     {"message", message}
                 });
@@ -100,10 +150,20 @@ public Task DetachAsync()
 
         #region Private Methods
 
+        /// <summary>
+        /// Releases all resource used by the <see cref="T:PuppeteerSharp.CDPSession"/> object by sending a ""Target.closeTarget"
+        /// using the <see cref="Connection.SendAsync(string, dynamic)"/> method.
+        /// </summary>
+        /// <remarks>Call <see cref="Dispose"/> when you are finished using the <see cref="PuppeteerSharp.CDPSession"/>. The
+        /// <see cref="Dispose"/> method leaves the <see cref="PuppeteerSharp.CDPSession"/> in an unusable state.
+        /// After calling <see cref="Dispose"/>, you must release all references to the
+        /// <see cref="PuppeteerSharp.CDPSession"/> so the garbage collector can reclaim the memory that the
+        /// <see cref="PuppeteerSharp.CDPSession"/> was occupying.</remarks>
         public void Dispose()
         {
-            Connection.SendAsync("Target.closeTarget", new Dictionary<string, object>() {
-                {"targetId", TargetId}
+            Connection.SendAsync("Target.closeTarget", new Dictionary<string, object>
+            {
+                ["targetId"] = TargetId
             }).GetAwaiter().GetResult();
         }
 

lib/PuppeteerSharp/Connection.cs

@@ -29,7 +29,7 @@ internal Connection(string url, int delay, ClientWebSocket ws, ILoggerFactory lo
             _logger = LoggerFactory.CreateLogger<Connection>();
             _socketQueue = new TaskQueue();
             _responses = new Dictionary<int, MessageTask>();
-            _sessions = new Dictionary<string, Session>();
+            _sessions = new Dictionary<string, CDPSession>();
             _websocketReaderCancellationSource = new CancellationTokenSource();
 
             Task task = Task.Factory.StartNew(async () =>
@@ -41,7 +41,7 @@ internal Connection(string url, int delay, ClientWebSocket ws, ILoggerFactory lo
         #region Private Members
         private int _lastId;
         private Dictionary<int, MessageTask> _responses;
-        private Dictionary<string, Session> _sessions;
+        private Dictionary<string, CDPSession> _sessions;
         private TaskQueue _socketQueue;
         private const string CloseMessage = "Browser.close";
         private bool _stopReading;
@@ -113,10 +113,10 @@ internal async Task<dynamic> SendAsync(string method, dynamic args = null)
             return await _responses[id].TaskWrapper.Task;
         }
 
-        internal async Task<Session> CreateSession(string targetId)
+        internal async Task<CDPSession> CreateSessionAsync(string targetId)
         {
             string sessionId = (await SendAsync("Target.attachToTarget", new { targetId })).sessionId;
-            var session = new Session(this, targetId, sessionId);
+            var session = new CDPSession(this, targetId, sessionId);
             _sessions.Add(sessionId, session);
             return session;
         }

lib/PuppeteerSharp/Dialog.cs

@@ -5,13 +5,13 @@ namespace PuppeteerSharp
 {
     public class Dialog
     {
-        private Session _client;
-        
+        private readonly CDPSession _client;
+
         public DialogType DialogType { get; set; }
         public string DefaultValue { get; set; }
         public string Message { get; set; }
 
-        public Dialog(Session client, DialogType type, string message, string defaultValue)
+        public Dialog(CDPSession client, DialogType type, string message, string defaultValue)
         {
             _client = client;
             DialogType = type;

lib/PuppeteerSharp/ElementHandle.cs

@@ -17,7 +17,7 @@ public class ElementHandle : JSHandle
     {
         internal Page Page { get; }
 
-        internal ElementHandle(ExecutionContext context, Session client, object remoteObject, Page page) :
+        internal ElementHandle(ExecutionContext context, CDPSession client, object remoteObject, Page page) :
             base(context, client, remoteObject)
         {
             Page = page;

lib/PuppeteerSharp/EmulationManager.cs

@@ -6,16 +6,16 @@ namespace PuppeteerSharp
 {
     internal class EmulationManager
     {
-        private Session _client;
+        private readonly CDPSession _client;
         private string _injectedTouchScriptId;
         private bool _emulatingMobile;
 
-        public EmulationManager(Session client)
+        public EmulationManager(CDPSession client)
         {
             _client = client;
         }
 
-        internal async Task<bool> EmulateViewport(Session client, ViewPortOptions viewport)
+        internal async Task<bool> EmulateViewport(CDPSession client, ViewPortOptions viewport)
         {
             var mobile = viewport.IsMobile;
             var width = viewport.Width;

lib/PuppeteerSharp/ExecutionContext.cs

@@ -13,10 +13,10 @@ namespace PuppeteerSharp
     /// </summary>
     public class ExecutionContext
     {
-        private readonly Session _client;
+        private readonly CDPSession _client;
         private readonly int _contextId;
 
-        internal ExecutionContext(Session client, ContextPayload contextPayload, Func<dynamic, JSHandle> objectHandleFactory)
+        internal ExecutionContext(CDPSession client, ContextPayload contextPayload, Func<dynamic, JSHandle> objectHandleFactory)
         {
             _client = client;
             _contextId = contextPayload.Id;

lib/PuppeteerSharp/Frame.cs

@@ -38,9 +38,8 @@ namespace PuppeteerSharp
     /// </example>
     public class Frame
     {
-        private readonly Session _client;
+        private readonly CDPSession _client;
         private readonly Page _page;
-
         private TaskCompletionSource<ElementHandle> _documentCompletionSource;
         private TaskCompletionSource<ExecutionContext> _contextResolveTaskWrapper;
 
@@ -49,14 +48,7 @@ public class Frame
         internal string LoaderId { get; set; }
         internal List<string> LifecycleEvents { get; }
 
-        /// <summary>
-        /// Initializes a new instance of the <see cref="Frame"/> class.
-        /// </summary>
-        /// <param name="client">The client</param>
-        /// <param name="page">The page containing the frame</param>
-        /// <param name="parentFrame">The parent frame</param>
-        /// <param name="frameId">The frameId</param>
-        public Frame(Session client, Page page, Frame parentFrame, string frameId)
+        internal Frame(CDPSession client, Page page, Frame parentFrame, string frameId)
         {
             _client = client;
             _page = page;
@@ -90,7 +82,7 @@ public Frame(Session client, Page page, Frame parentFrame, string frameId)
         /// Gets the frame's url
         /// </summary>
         public string Url { get; private set; }
-        
+
         /// <summary>
         /// Gets a value indicating if the frame is detached or not
         /// </summary>
@@ -215,7 +207,7 @@ function hasVisibleBoundingBox() {
             }, selector, options.Visible, options.Hidden);
             return handle as ElementHandle;
         }
-        
+
         /// <summary>
         /// Waits for a timeout
         /// </summary>
@@ -483,7 +475,7 @@ internal void SetDefaultContext(ExecutionContext context)
                 _contextResolveTaskWrapper = new TaskCompletionSource<ExecutionContext>();
             }
         }
-        
+
         internal void Detach()
         {
             while (WaitTasks.Count > 0)

lib/PuppeteerSharp/FrameManager.cs

@@ -10,12 +10,12 @@ namespace PuppeteerSharp
 {
     public class FrameManager
     {
-        private readonly Session _client;
+        private readonly CDPSession _client;
         private readonly Page _page;
-        private readonly Dictionary<int, ExecutionContext> _contextIdToContext;
+        private Dictionary<int, ExecutionContext> _contextIdToContext;
         private readonly ILogger _logger;
 
-        public FrameManager(Session client, FrameTree frameTree, Page page)
+        public FrameManager(CDPSession client, FrameTree frameTree, Page page)
         {
             _client = client;
             _page = page;