Merge dev into master (#268)

* Move cancellation token to correct location

* Add comments to AddAsync

* Add "id" parameter

* Internal constructor comments

* Replace invalid characters with HTML

* Code comments for constants

* ChunkedUpload comments

* OneDrive comments

* Resolve OneNote comments

* Serializer comments

* Update out-of-date comments

* Core constants

* Option comments

* Misc missing comments

* Collection page comments

* Add missing comments

* Add response headers to regular requests

* Handle case if content is empty

* Add SerializeObject method to MockSerializer

* .NET Core mock serializer update

* Update functional test items

* Don't add response headers to void response types

* Generate valid serializer response

* Response header test

* Assert expected headers match response headers

* Add documentation on headers

* Docs edits

* Refactor AddHeadersToResponse

* Add stream limitation documentation

* generated code files

* Add colon to GetByPath URL

* Functional test for GetByPath navigation

Updated site resource for new tenant

* Updates due to cneeded data updates in demo tenant.

* Updated package/assembly version, added release notes.

* Add DELETE/POST/PATCH to withReferenceRequest on entities

* withReferenceRequest interface updates

* Remove collection-specific code

README.md

@@ -91,6 +91,7 @@ The following sample applications are also available:
 * [Overview](docs/overview.md)
 * [Collections](docs/collections.md)
 * [Errors](docs/errors.md)
+* [Headers](docs/headers.md)
 * [Microsoft Graph API](https://graph.microsoft.io)
 * [Release notes](https://github.com/microsoftgraph/msgraph-sdk-dotnet/releases)
 

docs/headers.md

@@ -0,0 +1,53 @@
+# Headers in the Microsoft Graph .NET Client Library
+
+
+The .NET Client Library allows you to add your own custom request headers and inspect the response headers that come back from the Graph service.
+
+## Adding request headers
+
+Custom headers can be added by creating a new option collection and adding it to the request object:
+
+```csharp
+List<Option> options = new List<Option>();
+options.Add(new HeaderOption("Etag", etag));
+options.Add(new HeaderOption("If-Match", etag));
+options.Add(new QueryOption("$filter", filterQuery));
+
+var newObject = graphServiceClient
+	.Object
+	.Request(options)
+	.Patch(updatedObject);
+```
+
+You can also pass headers in individually if you only need to include one header:
+
+```csharp
+var newObject = graphServiceClient
+	.Object
+	.Request(new HeaderOption("Etag", etag))
+	.Patch(updatedObject);
+```
+
+## Reading response headers
+
+HTTP response data is available in the `AdditionalData` property bag of the response object. You can access both the `statusCode` of the response and the `responseHeaders` to get more information, such as the request ID, Content-Type, and other data that may be relevant to you that is not part of the object model inherently.
+
+To work with the response headers, you can deserialize the data using the client's serializer to make it easy to parse through the header dictionary:
+
+```csharp
+var user = await graphServiceClient....getAsync();
+
+var statusCode = user.AdditionalData["statusCode"];
+var responseHeaders = user.AdditionalData["responseHeaders"];
+
+// Deserialize headers to dictionary for easy access to values
+var responseHeaderCollection = graphClient
+                    .HttpProvider
+                    .Serializer
+                    .DeserializeObject<Dictionary<string, List<string>>>(responseHeaders.ToString());
+
+var requestId = responseHeaderCollection["request-id"][0];
+```
+
+
+*Currently, requests that have a return type of `void` or `Stream` do not return response headers and cannot be inspected.*

docs/readme.md

@@ -4,6 +4,7 @@
 * [Collections](./collections.md)
 * [Errors](./errors.md)
 * [Contributions](./contributions.md)
+* [Headers](./headers.md)
 * [FAQ](./FAQ.md)
 
 ## How do I work with...

src/Microsoft.Graph.Core/Authentication/DelegateAuthenticationProvider.cs

@@ -7,6 +7,11 @@ namespace Microsoft.Graph
     using System.Net.Http;
     using System.Threading.Tasks;
 
+    /// <summary>
+    /// Authenticate request async delegate.
+    /// </summary>
+    /// <param name="request">The <see cref="HttpRequestMessage"/> to authenticate.</param>
+    /// <returns></returns>
     public delegate Task AuthenticateRequestAsyncDelegate(HttpRequestMessage request);
 
     /// <summary>

src/Microsoft.Graph.Core/CoreConstants.cs

@@ -4,25 +4,43 @@
 
 namespace Microsoft.Graph
 {
+    /// <summary>
+    /// Constants for the Graph Core library.
+    /// </summary>
     public static class CoreConstants
     {
+        /// <summary>
+        /// Polling interval for task completion.
+        /// </summary>
         public const int PollingIntervalInMs = 5000;
 
+        /// <summary>
+        /// Header constants.
+        /// </summary>
         public static class Headers
         {
+            /// Authorization bearer.
             public const string Bearer = "Bearer";
 
+            /// SDK Version header
             public const string SdkVersionHeaderName = "SdkVersion";
 
+            /// SDK Version header
             public const string SdkVersionHeaderValueFormatString = "{0}-dotnet-{1}.{2}.{3}";
 
+            /// Content-Type header
             public const string FormUrlEncodedContentType = "application/x-www-form-urlencoded";
 
+            /// Throw-site header
             public const string ThrowSiteHeaderName = "X-ThrowSite";
         }
 
+        /// <summary>
+        /// Serialization constants.
+        /// </summary>
         public static class Serialization
         {
+            /// OData type
             public const string ODataType = "@odata.type";
         }
     }

src/Microsoft.Graph.Core/Exceptions/Error.cs

@@ -10,24 +10,46 @@ namespace Microsoft.Graph
     using System.Text;
     using Newtonsoft.Json;
 
+    /// <summary>
+    /// The error object that handles unsuccessful responses returned from the service.
+    /// </summary>
     [JsonObject(MemberSerialization = MemberSerialization.OptIn)]
     public class Error
     {
+        /// <summary>
+        /// The HTTP status code.
+        /// </summary>
         [JsonProperty(NullValueHandling = NullValueHandling.Ignore, PropertyName = "code", Required = Required.Default)]
         public string Code { get; set; }
 
+        /// <summary>
+        /// The inner error of the response. These are additional error objects that may be more specific than the top level error.
+        /// </summary>
         [JsonProperty(NullValueHandling = NullValueHandling.Ignore, PropertyName = "innererror", Required = Required.Default)]
         public Error InnerError { get; set; }
 
+        /// <summary>
+        /// The error message.
+        /// </summary>
         [JsonProperty(NullValueHandling = NullValueHandling.Ignore, PropertyName = "message", Required = Required.Default)]
         public string Message { get; set; }
 
+        /// <summary>
+        /// The Throw site of the error.
+        /// </summary>
         [JsonProperty(NullValueHandling = NullValueHandling.Ignore, PropertyName = "throwSite", Required = Required.Default)]
         public string ThrowSite { get; set; }
 
+        /// <summary>
+        /// The AdditionalData property bag.
+        /// </summary>
         [JsonExtensionData(ReadData = true)]
         public IDictionary<string, object> AdditionalData { get; set; }
 
+        /// <summary>
+        /// Concatenates the error into a string.
+        /// </summary>
+        /// <returns>A human-readable string error response.</returns>
         public override string ToString()
         {
             var errorStringBuilder = new StringBuilder();

src/Microsoft.Graph.Core/Exceptions/ErrorResponse.cs

@@ -8,12 +8,21 @@ namespace Microsoft.Graph
     using System.Runtime.Serialization;
     using Newtonsoft.Json;
 
+    /// <summary>
+    /// The error response object from the service on an unsuccessful call.
+    /// </summary>
     [JsonObject(MemberSerialization = MemberSerialization.OptIn)]
     public class ErrorResponse
     {
+        /// <summary>
+        /// The <see cref="Error"/> returned by the service.
+        /// </summary>
         [JsonProperty(PropertyName = "error")]
         public Error Error { get; set; }
 
+        /// <summary>
+        /// Additional data returned in the call.
+        /// </summary>
         [JsonExtensionData(ReadData = true)]
         public IDictionary<string, object> AdditionalData { get; set; }
     }

src/Microsoft.Graph.Core/Exceptions/ServiceException.cs

@@ -6,21 +6,40 @@ namespace Microsoft.Graph
 {
     using System;
 
+    /// <summary>
+    /// Graph service exception.
+    /// </summary>
     public class ServiceException : Exception
     {
+        /// <summary>
+        /// Creates a new service exception.
+        /// </summary>
+        /// <param name="error">The error that triggered the exception.</param>
+        /// <param name="innerException">The possible innerException.</param>
         public ServiceException(Error error, Exception innerException = null)
             : base(error?.ToString(), innerException)
         {
             this.Error = error;
         }
 
+        /// <summary>
+        /// The error from the service exception.
+        /// </summary>
         public Error Error { get; private set; }
 
-        // ResponseHeaders and StatusCode exposed as pass-through.
+        /// ResponseHeaders and StatusCode exposed as pass-through.
         public System.Net.Http.Headers.HttpResponseHeaders ResponseHeaders { get; internal set; }
 
+        /// <summary>
+        /// The HTTP status code from the response.
+        /// </summary>
         public System.Net.HttpStatusCode StatusCode { get; internal set; }
 
+        /// <summary>
+        /// Checks if a given error code has been returned in the response at any level in the error stack.
+        /// </summary>
+        /// <param name="errorCode">The error code.</param>
+        /// <returns>True if the error code is in the stack.</returns>
         public bool IsMatch(string errorCode)
         {
             if (string.IsNullOrEmpty(errorCode))

src/Microsoft.Graph.Core/Helpers/StringHelper.cs

@@ -6,6 +6,9 @@ namespace Microsoft.Graph
 {
     using System.Linq;
 
+    /// <summary>
+    /// Helper class for string casing.
+    /// </summary>
     public static class StringHelper
     {
         /// <summary>

src/Microsoft.Graph.Core/Helpers/UrlHelper.cs

@@ -8,8 +8,16 @@ namespace Microsoft.Graph
     using System.Collections.Generic;
     using System.Net;
 
+    /// <summary>
+    /// Helper class for working with URLs.
+    /// </summary>
     public static class UrlHelper
     {
+        /// <summary>
+        /// Parse query options from the URL.
+        /// </summary>
+        /// <param name="resultUri"></param>
+        /// <returns></returns>
         public static IDictionary<string, string> GetQueryOptions(Uri resultUri)
         {
             string[] queryParams = null;

src/Microsoft.Graph.Core/Microsoft.Graph.Core.csproj

@@ -3,20 +3,22 @@
     <Description>Microsoft Graph Core Client Library implements core functionality used by Microsoft Graph Client Libraries.</Description>
     <Copyright>Copyright (c) Microsoft Corporation</Copyright>
     <AssemblyTitle>Microsoft Graph Core Client Library</AssemblyTitle>
-    <VersionPrefix>1.8.0</VersionPrefix>
-    <FileVersion>1.8.0</FileVersion>
-    <AssemblyVersion>1.8.0</AssemblyVersion>
+    <VersionPrefix>1.9.0</VersionPrefix>
+    <FileVersion>1.9.0</FileVersion>
+    <AssemblyVersion>1.9.0</AssemblyVersion>
     <Authors>Microsoft</Authors>
     <TargetFrameworks>netstandard1.1;net45</TargetFrameworks>
     <PreserveCompilationContext>false</PreserveCompilationContext>
     <AssemblyName>Microsoft.Graph.Core</AssemblyName>
     <PackageId>Microsoft.Graph.Core</PackageId>
     <PackageTags>Microsoft Office365;Graph;GraphServiceClient;Outlook;OneDrive;AzureAD;GraphAPI;Productivity;SharePoint;Intune;SDK</PackageTags>
     <PackageReleaseNotes>
-      March 2018 Release Summary (version 1.8.0)
+May 2018 Release Summary (version 1.9.0)
 
-      New features
-      * Update Json.NET dependency to include 11.x
+New features
+- Added more comments.
+- Added response headers and status to all calls that return a non-stream object.
+- Added SerializeObject method to MockSerializer.
     </PackageReleaseNotes>
     <PackageProjectUrl>https://developer.microsoft.com/graph</PackageProjectUrl>
     <PackageLicenseUrl>http://aka.ms/devservicesagreement</PackageLicenseUrl>
@@ -36,7 +38,7 @@
     <DelaySign>True</DelaySign>
     <AssemblyOriginatorKeyFile>35MSSharedLib1024.snk</AssemblyOriginatorKeyFile>
     <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
-    <Version>1.8.0</Version>
+    <Version>1.9.0</Version>
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|netstandard1.1|AnyCPU'">
     <DocumentationFile>bin\Release\netstandard1.1\Microsoft.Graph.Core.xml</DocumentationFile>