Microsoft Graph .NET Client Library

README.md

@@ -1,18 +1,18 @@
-# Microsoft Graph SDK for C#
+# Microsoft Graph .NET Client Library
 
-Integrate the [Microsoft Graph API](https://graph.microsoft.io) into your C#
+Integrate the [Microsoft Graph API](https://graph.microsoft.io) into your .NET
 project!
 
-The Microsoft Graph SDK is built as a Portable Class Library and targets the
-following frameworks:
+The Microsoft Graph .NET Client Library is built as a Portable Class Library targeting profile 111.
+This targets the following frameworks:
 
-* .NET 4.5.1
+* .NET 4.5
 * .NET for Windows Store apps
 * Windows Phone 8.1 and higher
 
 ## Installation via NuGet
 
-To install the Graph SDK via NuGet:
+To install the client library via NuGet:
 
 * Search for `Microsoft.Graph` in the NuGet Library, or
 * Type `Install-Package Microsoft.Graph` into the Package Manager Console.
@@ -22,94 +22,63 @@ To install the Graph SDK via NuGet:
 ### 1. Register your application
 
 Register your application to use Microsoft Graph API using one of the following
-supported authentication providers:
+supported authentication portals:
 
 * [Microsoft Application Registration Portal](https://apps.dev.microsoft.com):
   Register a new application that works with Microsoft Account and/or
-  organizational accounts using the Azure unified authentication end point.
+  organizational accounts using the unified V2 Authentication Endpoint.
 * [Microsoft Azure Active Directory](https://manage.windowsazure.com): Register
   a new application in your tenant's Active Directory to support work or school
   users for your tenant or multiple tenants.
+
+### 2. Authenticate for the Microsoft Graph service
 
-### 2. Setting your application id and scopes
+The Microsoft Graph .NET Client Library does not include any default authentication implementations.
+Instead, the user will want to authenticate with the library of their choice, or against the OAuth
+endpoint directly, and built-in **DelegateAuthenticationProvider** class to authenticate each request.
+For more information on `DelegateAuthenticationProvider`, see the [library overview](docs/overview)
 
-Before being granted access to Microsoft Graph APIs your application requests
-consent from the user for the aspects of Microsoft Graph it will be using. These
-are defined using authorization scopes. Your application can either ask for all
-required permissions initially, or can request essential scopes and then request
-additional scopes as necessary.
+The recommended library for authenticating against AAD is [ADAL](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet).
 
-For more information on available scopes, see [Authentication scopes](https://dev.onedrive.com/auth/msa_oauth.htm#authentication-scopes).
+For an example of authenticating a UWP app using the V2 Authentication Endpoint, see the [Microsoft Graph UWP Connect Library](https://github.com/ginach/Microsoft-Graph-UWP-Connect-Library).
 
-### 3. Create a Microsoft Graph Client object with an authentication provider
+### 3. Create a Microsoft Graph client object with an authentication provider
 
-An instance of the **GraphServicesClient** class handles building requests,
+An instance of the **GraphServiceClient** class handles building requests,
 sending them to Microsoft Graph API, and processing the responses. To create a
 new instance of this class, you need to provide an instance of
-IAuthenticationProvider which can authenticate requests to Microsoft Graph.
+`IAuthenticationProvider` which can authenticate requests to Microsoft Graph.
 
-For consumer and converged scenarios, you can use the OAuth2AuthProvider supplied
-by the **Microsoft.Graph.OAuth** NuGet package.
-
-```csharp
-var scopes = new string[] {
-  "https://graph.microsoft.com/files.readwrite",
-  "https://graph.microsoft.com/users.read",
-  "https://graph.microsoft.com/mail.read"
-};
-var authProvider = new Microsoft.Graph.OAuth2AuthProvider("app_id", scopes)
-var graphClient = new Microsoft.Graph.GraphServicesClient("https://graph.microsoft.com", authProvider);
-```
-
-Before using the newly created **graphCliet** object, you need to have the user
-login and consent to the requested scopes. You initiate the login flow by calling
-**LoginAsync()** on the **OAuth2AuthProvider** instance.
-
-```csharp
-await authProvider.LoginAsync();
-```
-
-For more information on using the OAuth2AuthProvider, see
-[Using the OAuth2 Authentication Provider](docs/oauth2authprovider.md).
-
-For enterprise and advanced scenarios, you can use ADAL or another authentication
-library and built-in **DelegateAuthProvider** class to authenticate each request. For an
-example, see
-[more information about using ADAL with Microsoft Graph SDK](docs/UsingAdalWithGraphSDK.md).
+For more information on initializing a client instance, see the [library overview](docs/overview)
 
 ### 4. Make requests to the graph
 
-Once you have completed authentication and have a GraphServicesClient, you can
+Once you have completed authentication and have a GraphServiceClient, you can
 begin to make calls to the service. The requests in the SDK follow the format
 of the Microsoft Graph API's RESTful syntax.
 
-For example, to retrieve a user's OneDrive:
+For example, to retrieve a user's default drive:
 
 ```csharp
 var drive = await graphClient.Me.Drive.Request().GetAsync();
 ```
 
 `GetAsync` will return a `Drive` object on success and throw a
-`GraphException` on error.
+`ServiceException` on error.
 
-To get the current user's root folder of their OneDrive:
+To get the current user's root folder of their default drive:
 
 ```csharp
 var rootItem = await graphClient.Me.Drive.Root.Request().GetAsync();
 ```
 
 `GetAsync` will return a `DriveItem` object on success and throw a
-`GraphException` on error.
+`ServiceException` on error.
 
 For a general overview of how the SDK is designed, see [overview](docs/overview.md).
 
 The following sample applications are also available:
-* [OneDrive API Browser](samples/OneDriveApiBrowser) - Windows Forms app
-* [OneDrive Photo Browser](samples/OneDrivePhotoBrowser) - Windows Universal app
-
-To run the OneDrivePhotoBrowser sample app your machine will need to be
-configured for [UWP app development](https://msdn.microsoft.com/en-us/library/windows/apps/dn609832.aspx)
-and the project must be associated with the Windows Store.
+* [Microsoft Graph UWP Connect Library](https://github.com/ginach/Microsoft-Graph-UWP-Connect-Library) - Windows Universal app
 
 ## Documentation and resources
 
@@ -122,13 +91,13 @@ and the project must be associated with the Windows Store.
 
 ## Issues
 
-To view or log issues, see [issues](https://github.com/OneDrive/onedrive-sdk-csharp/issues).
+To view or log issues, see [issues](https://github.com/microsoftgraph/msgraph-sdk-dotnet/issues).
 
 ## Other resources
 
-* NuGet Package: [https://www.nuget.org/packages/Microsoft.OneDriveSDK](https://www.nuget.org/packages/Microsoft.OneDriveSDK)
+* NuGet Package: [https://www.nuget.org/packages/Microsoft.Graph](https://www.nuget.org/packages/Microsoft.Graph)
 
 
 ## License
 
-[License](LICENSE.txt)
+Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT [license](LICENSE.txt)

common/Microsoft.Graph.nuspec

@@ -3,24 +3,24 @@
   <metadata>
     <id>Microsoft.Graph</id>
     <version>1.0.0</version>
-    <title>Microsoft Graph .NET SDK</title>
+    <title>Microsoft Graph Client Library</title>
     <authors>Microsoft</authors>
     <owners>Microsoft</owners>
     <requireLicenseAcceptance>true</requireLicenseAcceptance>
-    <description>Integrate the Microsoft Graph API into your .NET app!</description>
-    <copyright>Copyright 2016 Microsoft Corporation</copyright>
-    <projectUrl>https://github.com/microsoftgraph/sdk-dotnet</projectUrl>
-    <licenseUrl>http://msdn.microsoft.com/en-US/cc300389</licenseUrl>
-    <tags>microsoft graph o365 outlook exchange sharepoint onedrive files cloud storage windowsphone windowsstore metro xaml html</tags>
+    <summary>Microsoft Graph Client Library allows you to call Office 365, Azure AD and other Microsoft services through a single unified developer experience.</summary>
+    <description>This package includes the client libraries for connecting your app to the Microsoft Graph. Microsoft Graph enables your app to interact with data entities and their relationships from many Microsoft cloud services with a unified developer experience. Learn more about Microsoft Graph at http://graph.microsoft.io.</description>
+    <copyright>Copyright (c) Microsoft Corporation</copyright>
+    <projectUrl>https://graph.microsoft.io</projectUrl>
+    <licenseUrl>http://aka.ms/devservicesagreement</licenseUrl>
+    <tags>Microsoft Office365 Graph GraphServiceClient Outlook OneDrive AzureAD GraphAPI Productivity SharePoint SDK</tags>
     <dependencies>
       <group>
-        <dependency id="Newtonsoft.Json" version="8.0.2" />
+        <dependency id="Newtonsoft.Json" version="6.0.2" />
       </group>
     </dependencies>
-
   </metadata>
   <files>
     <!-- PCL projects -->
-    <file src="..\src\OneDriveSdk\bin\Release\Microsoft.Graph.dll" target="lib\portable-net45+netcore45+wpa81+win8\Microsoft.Graph.dll" />
+    <file src="..\src\Microsoft.Graph\bin\Release\Microsoft.Graph.dll" target="lib\portable-net45+netcore45+wpa81+win8\Microsoft.Graph.dll" />
   </files>
-</package>
+</package>

docs/collections.md

@@ -0,0 +1,61 @@
+Collections in the Microsoft Graph .NET Client Library
+=====
+
+Whenever a request returns a collection of objects that allow paging or navigation into the collection, the library generates a complex collection page object.
+
+## Getting a collection
+
+To retrieve a collection, like the list of groups in the service, you call `GetAsync` on the collection request:
+
+```csharp
+await graphServiceClient
+	    .Groups
+	    .Request()
+	    .GetAsync();
+```
+
+`GetAsync` returns an `ICollectionPage<T>` implementation on success and throws a `ServiceException` on error. For the groups collection, the type returned is `IGraphServiceGroupsCollectionPage`, which inherits `ICollectionPage<Item>`.
+
+`IGraphServiceGroupsCollectionPage` contains three properties: 
+
+|Name                |Description                                                                                                                                                  |
+|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|**CurrentPage**     |An `IList<Item>`.                                                                                                                                            |
+|**NextPageRequest** |An `IGraphServiceGroupsCollectionRequest` used to get to the next page of items, if another page exists. This value will be null if there is not a next page.|
+|**AdditionData**    |An `IDictionary<string, object>` to any additional values returned by the service. In this case, none.                                                       |
+
+## Adding to a collection
+
+Some collections, like the groups collection, can be changed. To create a group you can call:
+
+```csharp
+var groupToCreate = new Group
+    {
+		GroupTypes = new List<string> { "Unified" },
+		DisplayName = "Unified group",
+		Description = "Best group ever",
+		...
+	};
+
+var newGroup = await graphServiceClient
+                         .Groups
+						 .Request()
+						 .AddAsync(groupToCreate);
+```
+
+`AddAsync` returns the created group on success and throws a `ServiceException` on error.
+
+## Expanding a collection
+
+To expand a collection, you call `Expand` on the collection request object with the string value of the expand:
+
+```csharp
+var children = await graphServiceClient
+                         .Me
+                         .Drive
+						 .Items[itemId]
+						 .Children
+						 .Request()
+						 .Expand("thumbnails")
+						 .GetAsync();
+```

docs/contributions.md

@@ -0,0 +1,28 @@
+Contributing to the Microsoft Graph .NET Client Library
+=====
+
+The Microsoft Graph .NET Client Library is avaliable for all manner of contribution. There are a few different recommended paths to get contributions into the released version of this library.
+
+**NOTE** A signed a contribution license agreement is required for all contributions and is checked automatically on new pull requests. Please read and sign the agreement https://cla.microsoft.com/ before starting any work for this repository.
+
+## File issues
+
+The best way to get started with a contribution is to start a dialog with the owners of the repository. Sometimes features will be under development or out of scope for this library and it's best to check before starting work on contribution.
+
+## Pull requests
+
+If you are making documentation changes, feel free to submit a pull request against the **master** branch. All other pull requests should be submitted against the **dev** branch or a specific **feature** branch. The **master** branch is intended to represent the code released in the most-recent Nuget package.
+
+When a new package is about to be released, changes in **dev** will be merged into **master**. The package will be generated from **master**.
+
+## Submit pull requests for trivial changes
+
+If you are making a change that does not affect the interface components and does not affect other downstream callers, feel free to make a pull request against the **dev** branch.
+
+Revisions of this nature will result in a 0.0.X change of the version number.
+
+## Submit pull requests for features
+
+If major functionality is being added it should be submitted against the **dev** branch. If the functionality will require multiple changes or iterations before it is ready for **dev**, feel free to submit pull requests into a dedicated **feature** branch until the whole change is ready.
+
+Revisions of this nature will result in a 0.X.X change of the version number.

docs/errors.md

@@ -0,0 +1,22 @@
+Handling errors in the Microsoft Graph .NET Client Library
+=====
+
+Errors in the Microsoft Graph .NET Client Library behave like errors returned from the Microsoft Graph service. You can read more about them [here](https://graph.microsoft.io/en-us/docs/overview/errors).
+
+Anytime you make a request against the service there is the potential for an error. In the case of an error, the request will throw a `ServiceException` object with an inner `Error` object that contains the service error details.
+
+## Checking the error
+
+There are a few different types of errors that can occur during a network call. These error codes are defined in [GraphErrorCode.cs](../src/Microsoft.Graph/Enums/GraphErrorCode.cs).
+
+### Checking the error code
+You can easily check if an error has a specific code by calling `IsMatch` on the error code value. `IsMatch` is not case sensitive:
+
+```csharp
+if (exception.IsMatch(GraphErrorCode.AccessDenied.ToString())
+{
+        // Handle access denied error
+}
+```
+
+Each error object has a `Message` property as well as code. This message is for debugging purposes and is not be meant to be displayed to the user. Common error codes are defined in [GraphErrorCode.cs](../src/Microsoft.Graph/Enums/GraphErrorCode.cs).