implement onedrive graph client and docs

KSemenenko · KSemenenko · commit 760fabd27637 · 2025-12-14T17:03:22.000+01:00
diff --git a/README.md b/README.md
@@ -52,6 +52,66 @@ Cloud storage vendors expose distinct SDKs, option models, and authentication pa
 | [ManagedCode.Storage.FileSystem](https://www.nuget.org/packages/ManagedCode.Storage.FileSystem) | [![NuGet](https://img.shields.io/nuget/v/ManagedCode.Storage.FileSystem.svg)](https://www.nuget.org/packages/ManagedCode.Storage.FileSystem) | Local file system implementation for hybrid or on-premises workloads. |
 | [ManagedCode.Storage.Sftp](https://www.nuget.org/packages/ManagedCode.Storage.Sftp) | [![NuGet](https://img.shields.io/nuget/v/ManagedCode.Storage.Sftp.svg)](https://www.nuget.org/packages/ManagedCode.Storage.Sftp) | SFTP provider powered by SSH.NET for legacy and air-gapped environments. |
 
+### Configuring OneDrive, Google Drive, and Dropbox
+
+> iCloud does not expose a public file API suitable for server-side integrations, so only Microsoft, Google, and Dropbox cloud drives are covered here.
+
+**OneDrive / Microsoft Graph**
+
+1. Create an app registration in Azure Active Directory (Entra ID) and record the **Application (client) ID**, **Directory (tenant) ID**, and a **client secret**.
+2. Add the Microsoft Graph **Files.ReadWrite.All** delegated permission (or **Sites.ReadWrite.All** if you target SharePoint drives) and grant admin consent.
+3. In your ASP.NET app, acquire a token via `ClientSecretCredential` or another `TokenCredential` and pass it to `new GraphServiceClient(credential, new[] { "https://graph.microsoft.com/.default" })`.
+4. Register OneDrive storage with the Graph client and the drive/root you want to scope to:
+
+   ```csharp
+   builder.Services.AddOneDriveStorageAsDefault(options =>
+   {
+       options.GraphClient = graphClient;        // from step 3
+       options.DriveId = "me";                   // or a specific drive ID
+       options.RootPath = "app-data";            // folder will be created when CreateContainerIfNotExists is true
+       options.CreateContainerIfNotExists = true;
+   });
+   ```
+
+5. If you need to impersonate a specific drive item, swap `DriveId` for the drive GUID returned by Graph.
+
+**Google Drive**
+
+1. In [Google Cloud Console](https://console.cloud.google.com/), create a project and enable the **Google Drive API**.
+2. Configure an OAuth consent screen and create an **OAuth 2.0 Client ID** (Desktop or Web). Record the client ID and secret.
+3. Exchange the OAuth code for a refresh token with the `https://www.googleapis.com/auth/drive.file` scope (or broader if necessary).
+4. Add the Google Drive provider and feed the credentials to the options:
+
+   ```csharp
+   builder.Services.AddGoogleDriveStorage(options =>
+   {
+       options.ClientId = configuration["GoogleDrive:ClientId"]!;
+       options.ClientSecret = configuration["GoogleDrive:ClientSecret"]!;
+       options.RefreshToken = configuration["GoogleDrive:RefreshToken"]!;
+       options.RootFolderId = "root"; // or a shared drive folder id
+   });
+   ```
+
+5. Store tokens in user secrets or environment variables; never commit them to source control.
+
+**Dropbox**
+
+1. Create an app in the [Dropbox App Console](https://www.dropbox.com/developers/apps) and choose **Scoped access** with the **Full Dropbox** or **App folder** type.
+2. Under **Permissions**, enable `files.content.write`, `files.content.read`, and `files.metadata.write` and generate a refresh token via OAuth.
+3. Register Dropbox storage with the access credentials and a root path (use `/` for full access apps or `/Apps/<your-app>` for app folders):
+
+   ```csharp
+   builder.Services.AddDropboxStorage(options =>
+   {
+       options.AppKey = configuration["Dropbox:AppKey"]!;
+       options.AppSecret = configuration["Dropbox:AppSecret"]!;
+       options.RefreshToken = configuration["Dropbox:RefreshToken"]!;
+       options.RootPath = "/apps/my-app";
+   });
+   ```
+
+4. Dropbox issues short-lived access tokens from refresh tokens; the SDK handles the exchange automatically once configured.
+
 ### ASP.NET & Clients
 
 | Package | Latest | Description |
diff --git a/Storages/ManagedCode.Storage.OneDrive/Clients/GraphOneDriveClient.cs b/Storages/ManagedCode.Storage.OneDrive/Clients/GraphOneDriveClient.cs
@@ -22,37 +22,199 @@ public GraphOneDriveClient(GraphServiceClient graphServiceClient)
 
     public Task EnsureRootAsync(string driveId, string rootPath, bool createIfNotExists, CancellationToken cancellationToken)
     {
-        // Graph-backed provisioning is not executed in this offline wrapper.
-        return Task.CompletedTask;
+        return EnsureRootInternalAsync(driveId, rootPath, createIfNotExists, cancellationToken);
     }
 
     public Task<DriveItem> UploadAsync(string driveId, string path, Stream content, string? contentType, CancellationToken cancellationToken)
     {
-        throw new NotSupportedException("Graph upload requires a configured OneDrive runtime environment.");
+        return UploadInternalAsync(driveId, path, content, contentType, cancellationToken);
     }
 
     public Task<Stream> DownloadAsync(string driveId, string path, CancellationToken cancellationToken)
     {
-        throw new NotSupportedException("Graph download requires a configured OneDrive runtime environment.");
+        return DownloadInternalAsync(driveId, path, cancellationToken);
     }
 
     public Task<bool> DeleteAsync(string driveId, string path, CancellationToken cancellationToken)
     {
-        throw new NotSupportedException("Graph deletion requires a configured OneDrive runtime environment.");
+        return DeleteInternalAsync(driveId, path, cancellationToken);
     }
 
     public Task<bool> ExistsAsync(string driveId, string path, CancellationToken cancellationToken)
     {
-        return Task.FromResult(false);
+        return ExistsInternalAsync(driveId, path, cancellationToken);
     }
 
     public Task<DriveItem?> GetMetadataAsync(string driveId, string path, CancellationToken cancellationToken)
     {
-        return Task.FromResult<DriveItem?>(null);
+        return GetMetadataInternalAsync(driveId, path, cancellationToken);
     }
 
     public IAsyncEnumerable<DriveItem> ListAsync(string driveId, string? directory, CancellationToken cancellationToken)
     {
-        return AsyncEnumerable.Empty<DriveItem>();
+        return ListInternalAsync(driveId, directory, cancellationToken);
+    }
+
+    private async Task EnsureRootInternalAsync(string driveId, string rootPath, bool createIfNotExists, CancellationToken cancellationToken)
+    {
+        var normalizedRoot = NormalizePath(rootPath);
+        if (string.IsNullOrWhiteSpace(normalizedRoot) || normalizedRoot == "/")
+        {
+            return;
+        }
+
+        var root = await GetRootDriveItemAsync(driveId, cancellationToken).ConfigureAwait(false);
+        var parentId = root.Id ?? throw new InvalidOperationException("Drive root is unavailable for the configured account.");
+        var segments = normalizedRoot.Split('/', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        foreach (var segment in segments)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var existing = await FindChildAsync(driveId, parentId, segment, cancellationToken).ConfigureAwait(false);
+            if (existing != null)
+            {
+                parentId = existing.Id!;
+                continue;
+            }
+
+            if (!createIfNotExists)
+            {
+                throw new DirectoryNotFoundException($"Folder '{normalizedRoot}' is missing in the configured drive.");
+            }
+
+            var childrenBuilder = await GetChildrenBuilderAsync(driveId, parentId, cancellationToken).ConfigureAwait(false);
+            var created = await childrenBuilder.PostAsync(new DriveItem
+            {
+                Name = segment,
+                Folder = new Folder()
+            }, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+            parentId = created?.Id ?? throw new InvalidOperationException($"Failed to create OneDrive folder '{segment}'.");
+        }
+    }
+
+    private async Task<DriveItem> UploadInternalAsync(string driveId, string path, Stream content, string? contentType, CancellationToken cancellationToken)
+    {
+        var rootBuilder = await GetRootItemBuilderAsync(driveId, cancellationToken).ConfigureAwait(false);
+        var request = rootBuilder.ItemWithPath(NormalizePath(path)).Content;
+        var response = await request.PutAsync(content, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+        return response ?? throw new InvalidOperationException("Graph upload returned no item.");
+    }
+
+    private async Task<Stream> DownloadInternalAsync(string driveId, string path, CancellationToken cancellationToken)
+    {
+        var rootBuilder = await GetRootItemBuilderAsync(driveId, cancellationToken).ConfigureAwait(false);
+        var request = rootBuilder.ItemWithPath(NormalizePath(path)).Content;
+        var stream = await request.GetAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+        return stream ?? throw new FileNotFoundException($"File '{path}' not found in OneDrive.");
+    }
+
+    private async Task<bool> DeleteInternalAsync(string driveId, string path, CancellationToken cancellationToken)
+    {
+        try
+        {
+            var rootBuilder = await GetRootItemBuilderAsync(driveId, cancellationToken).ConfigureAwait(false);
+            await rootBuilder.ItemWithPath(NormalizePath(path)).DeleteAsync(cancellationToken: cancellationToken)
+                .ConfigureAwait(false);
+            return true;
+        }
+        catch (ODataError ex) when (ex.ResponseStatusCode == 404)
+        {
+            return false;
+        }
+    }
+
+    private async Task<bool> ExistsInternalAsync(string driveId, string path, CancellationToken cancellationToken)
+    {
+        var item = await GetMetadataInternalAsync(driveId, path, cancellationToken).ConfigureAwait(false);
+        return item != null;
+    }
+
+    private async Task<DriveItem?> GetMetadataInternalAsync(string driveId, string path, CancellationToken cancellationToken)
+    {
+        try
+        {
+            var rootBuilder = await GetRootItemBuilderAsync(driveId, cancellationToken).ConfigureAwait(false);
+            return await rootBuilder.ItemWithPath(NormalizePath(path)).GetAsync(cancellationToken: cancellationToken)
+                .ConfigureAwait(false);
+        }
+        catch (ODataError ex) when (ex.ResponseStatusCode == 404)
+        {
+            return null;
+        }
+    }
+
+    private async IAsyncEnumerable<DriveItem> ListInternalAsync(string driveId, string? directory, [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        var normalized = string.IsNullOrWhiteSpace(directory) ? null : NormalizePath(directory!);
+        var resolvedDriveId = await ResolveDriveIdAsync(driveId, cancellationToken).ConfigureAwait(false);
+        var parent = normalized == null
+            ? await _graphServiceClient.Drives[resolvedDriveId].Root.GetAsync(cancellationToken: cancellationToken).ConfigureAwait(false)
+            : await _graphServiceClient.Drives[resolvedDriveId].Root.ItemWithPath(normalized).GetAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+
+        if (parent?.Id == null)
+        {
+            yield break;
+        }
+
+        var builder = _graphServiceClient.Drives[resolvedDriveId].Items[parent.Id].Children;
+        var page = await builder.GetAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+        if (page?.Value == null)
+        {
+            yield break;
+        }
+
+        foreach (var item in page.Value)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            if (item != null)
+            {
+                yield return item;
+            }
+        }
+    }
+
+    private async Task<Microsoft.Graph.Drives.Item.Root.RootRequestBuilder> GetRootItemBuilderAsync(string driveId, CancellationToken cancellationToken)
+    {
+        var resolvedDriveId = await ResolveDriveIdAsync(driveId, cancellationToken).ConfigureAwait(false);
+        return _graphServiceClient.Drives[resolvedDriveId].Root;
+    }
+
+    private async Task<Microsoft.Graph.Drives.Item.Items.Item.Children.ChildrenRequestBuilder> GetChildrenBuilderAsync(string driveId, string parentId, CancellationToken cancellationToken)
+    {
+        var resolvedDriveId = await ResolveDriveIdAsync(driveId, cancellationToken).ConfigureAwait(false);
+        return _graphServiceClient.Drives[resolvedDriveId].Items[parentId].Children;
+    }
+
+    private async Task<DriveItem> GetRootDriveItemAsync(string driveId, CancellationToken cancellationToken)
+    {
+        var resolvedDriveId = await ResolveDriveIdAsync(driveId, cancellationToken).ConfigureAwait(false);
+        var root = await _graphServiceClient.Drives[resolvedDriveId].Root.GetAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+        return root ?? throw new InvalidOperationException("Drive root is unavailable for the configured account.");
+    }
+
+    private async Task<string> ResolveDriveIdAsync(string driveId, CancellationToken cancellationToken)
+    {
+        if (!driveId.Equals("me", StringComparison.OrdinalIgnoreCase))
+        {
+            return driveId;
+        }
+
+        var drive = await _graphServiceClient.Me.Drive.GetAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+        return drive?.Id ?? throw new InvalidOperationException("Unable to resolve the current user's drive id.");
+    }
+
+    private async Task<DriveItem?> FindChildAsync(string driveId, string parentId, string name, CancellationToken cancellationToken)
+    {
+        var childrenBuilder = await GetChildrenBuilderAsync(driveId, parentId, cancellationToken).ConfigureAwait(false);
+        var children = await childrenBuilder.GetAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
+
+        return children?.Value?.FirstOrDefault(c => string.Equals(c?.Name, name, StringComparison.OrdinalIgnoreCase));
+    }
+
+    private static string NormalizePath(string path)
+    {
+        return path.Replace("\\", "/").Trim('/');
     }
 }
diff --git a/Storages/ManagedCode.Storage.OneDrive/OneDriveStorage.cs b/Storages/ManagedCode.Storage.OneDrive/OneDriveStorage.cs
@@ -57,7 +57,7 @@ protected override async Task<Result> CreateContainerInternalAsync(CancellationT
     public override Task<Result> RemoveContainerAsync(CancellationToken cancellationToken = default)
     {
         // OneDrive containers map to drives or root folders that are typically managed by the account owner.
-        return Task.FromResult(Result.Succeed());
+        return Task.FromResult(Result.Fail(new NotSupportedException("Deleting a OneDrive container is not supported.")));
     }
 
     protected override async Task<Result> DeleteDirectoryInternalAsync(string directory, CancellationToken cancellationToken = default)
diff --git a/Tests/ManagedCode.Storage.Tests/Storages/CloudDrive/CloudDriveStorageTests.cs b/Tests/ManagedCode.Storage.Tests/Storages/CloudDrive/CloudDriveStorageTests.cs
@@ -57,6 +57,21 @@ public async Task OneDrive_FakeClient_RoundTrip()
         listed.ShouldContain(m => m.FullName.EndsWith("text.txt"));
     }
 
+    [Fact]
+    public async Task OneDrive_RemoveContainer_NotSupported()
+    {
+        var fakeClient = new FakeOneDriveClient();
+        var storage = new OneDriveStorage(new OneDriveStorageOptions
+        {
+            Client = fakeClient,
+            DriveId = "drive",
+            RootPath = "root"
+        });
+
+        var result = await storage.RemoveContainerAsync();
+        result.IsSuccess.ShouldBeFalse();
+    }
+
     [Fact]
     public async Task GoogleDrive_FakeClient_RoundTrip()
     {
diff --git a/Tests/ManagedCode.Storage.Tests/Storages/CloudDrive/GraphOneDriveClientTests.cs b/Tests/ManagedCode.Storage.Tests/Storages/CloudDrive/GraphOneDriveClientTests.cs

Original file line number	Diff line number	Diff line change
`@@ -57,7 +57,7 @@ protected override async Task<Result> CreateContainerInternalAsync(CancellationT`
`57`	`57`	`public override Task<Result> RemoveContainerAsync(CancellationToken cancellationToken = default)`
`58`	`58`	`{`
`59`	`59`	`// OneDrive containers map to drives or root folders that are typically managed by the account owner.`
`60`		`- return Task.FromResult(Result.Succeed());`
	`60`	`+ return Task.FromResult(Result.Fail(new NotSupportedException("Deleting a OneDrive container is not supported.")));`
`61`	`61`	`}`
`62`	`62`
`63`	`63`	`protected override async Task<Result> DeleteDirectoryInternalAsync(string directory, CancellationToken cancellationToken = default)`