Documentation: System properties (Json property documentation) (#347)

* Adding sample

* Adding comment

* Addressing comments

* Tests

* More texts

Microsoft.Azure.Cosmos.Samples/CodeSamples/ItemManagement/Program.cs

@@ -36,6 +36,8 @@
     // 3. Using ETags to control execution
     // 3.1 - Use ETag with ReplaceItem for optimistic concurrency
     // 3.2 - Use ETag with ReadItem to only return a result if the ETag of the request does not match
+    //
+    // 4 - Access items system defined properties
     //-----------------------------------------------------------------------------------------------------------
     // See Also - 
     //
@@ -120,6 +122,8 @@
             await Program.UseETags();
 
             await Program.UseConsistencyLevels();
+
+            await Program.AccessSystemDefinedProperties();
         }
 
         /// <summary>
@@ -636,6 +640,35 @@
             Console.WriteLine("Read doc with StatusCode of {0}", response.StatusCode);
         }
 
+        /// <summary>
+        /// 4. Access items system defined properties
+        /// </summary>
+        /// <returns></returns>
+        private static async Task AccessSystemDefinedProperties()
+        {
+            //******************************************************************************************************************
+            // Items contain attributes that are system defined:
+            // Timestamp : Gets the last modified timestamp associated with the item from the Azure Cosmos DB service.
+            // Etag : Gets the entity tag associated with the item from the Azure Cosmos DB service.
+            // TimeToLive : Gets the time to live in seconds of the item in the Azure Cosmos DB service.
+            // 
+            // See also: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items#azure-cosmos-containers
+            //******************************************************************************************************************
+            Console.WriteLine("\n4 - Accessing system defined properties");
+
+            //read a item's metadata
+
+            Metadata itemResponse = await container.Items.ReadItemAsync<Metadata>(
+                partitionKey: "Account1",
+                id: "SalesOrder1");
+
+            Console.WriteLine("ETag of read item - {0}", itemResponse.Etag);
+
+            Console.WriteLine("TimeToLive of read item - {0}", itemResponse.TimeToLive);
+
+            Console.WriteLine("Timestamp of read item - {0}", itemResponse.Timestamp.ToShortDateString());
+        }
+
         private static async Task UseConsistencyLevels()
         {
             // Override the consistency level for a read request

Microsoft.Azure.Cosmos.Samples/CodeSamples/Shared/Metadata.cs

@@ -0,0 +1,28 @@
+namespace Cosmos.Samples.Shared
+{
+    using System;
+    using Newtonsoft.Json;
+    using Newtonsoft.Json.Converters;
+
+    public class Metadata
+    {
+        /// <summary>
+        /// Gets the time to live in seconds of the item in the Azure Cosmos DB service.
+        /// </summary>
+        [JsonProperty(NullValueHandling = NullValueHandling.Ignore, PropertyName = "ttl")]
+        public int? TimeToLive { get; set; }
+
+        /// <summary>
+        /// Gets the entity tag associated with the item from the Azure Cosmos DB service.
+        /// </summary>
+        [JsonProperty("_etag")]
+        public string Etag { get; set; }
+
+        /// <summary>
+        /// Gets the last modified timestamp associated with the item from the Azure Cosmos DB service.
+        /// </summary>
+        [JsonConverter(typeof(UnixDateTimeConverter))]
+        [JsonProperty("_ts")]
+        public DateTime Timestamp { get; set; }
+    }
+}

Microsoft.Azure.Cosmos/src/Resource/Item/CosmosItems.cs

@@ -168,6 +168,12 @@ namespace Microsoft.Azure.Cosmos
         /// <returns>
         /// A <see cref="Task"/> containing a <see cref="ItemResponse{T}"/> which wraps the read resource record.
         /// </returns>
+        /// <remarks>
+        /// Items contain metadata that can be obtained by mapping these metadata attributes to properties in <typeparamref name="T"/>.
+        /// * "_ts": Gets the last modified timestamp associated with the item from the Azure Cosmos DB service.
+        /// * "_etag": Gets the entity tag associated with the item from the Azure Cosmos DB service.
+        /// * "ttl": Gets the time to live in seconds of the item in the Azure Cosmos DB service.
+        /// </remarks>
         /// <exception cref="CosmosException">This exception can encapsulate many different types of errors. To determine the specific error always look at the StatusCode property. Some common codes you may get when creating a Document are:
         /// <list type="table">
         ///     <listheader>