DotNetBox¶

The .NET Framework for Dropbox¶

Getting Started¶

Download¶

DotNetBox can be downloaded on NuGet or by using the NuGet Package Manager. If you are using Visual Studio, do the following:

Open the package manager by going to Tools > NuGet Package Manager > Package Manager Console
Type Install-Package DotNetBox.

Using the DropboxClient Class¶

There are two ways to create an instance of the DropboxClient class. You can either create it using an access token you have already retrieved,

DropboxClient client = new DropboxClient("YOUR_ACCESS_TOKEN");

or by using your registered app’s key and secret (get them from the My Apps section of the Dropbox Developers website).

DropboxClient client = new DropboxClient("APP_KEY", "APP_SECRET");

Using an access token will instantly give you the ability to call any API endpoint. However, if you chose the latter, you will need to authorize the user by redirecting them to the authorization webpage. To get the URL of this page, you need to call the GetAuthorizeUrl() function. You will need to specify a response type to call the function. For the sake of this tutorial, we will be using the Code flow.

string authorizeUrl = client.GetAuthorizeUrl(ResponseType.Code);

Using the Code flow means that the authorization web page will display, once the user accepts, a code that the user then has to enter into your app. You will need to pass this code to the AuthorizeCode() function.

await client.AuthorizeCode("USER'S_CODE");

Here is an example of a simple authorization client:

DropboxClient client = new DropboxClient("APP_KEY", "APP_SECRET"); // create the client

private void GetCodeButton_Click()
{
        Process.Start(client.GetAuthorizeUrl(ResponseType.Code)) // this will open the authorization URL in the user's default browser
}

private async void GetAccessTokenButton_Click()
{
        await client.AuthorizeCode(CodeTextBox.Text); // authorize the code the user entered in a text box
}

You will now be able to call API endpoints.

Calling your first endpoint¶

Getting the user’s information¶

You are now ready to use Dropbox’s API! To start off, get the current user’s information by calling the GetCurrentAccount() function.

FullAccount currentAccount = await client.Users.GetCurrentAccount();

This will give you access to information such as the user’s account ID, their name and email, their referral link, their account type, and more! You can use this information to display who is connected to your application.

You can also get the current user’s space usage by calling the GetSpaceUsage() function.

SpaceUsage spaceUsage = await client.Users.GetSpaceUsage();

This gives you the user’s current space usage and their space quota.

File management¶

Dropbox is a file storage service; therefore, there must be API endpoints for file management, right? Of course! We will cover the most basic ones, but you can check out all of them in the left sidebar, and most of them are quite self-explanatory.

Getting metadata¶

The first endpoint we will use is the GetMetadata() function. It retrieves a file or folder’s metadata. It is important to either call FileExists() or FolderExists() before calling this function, because it will throw an exception if the file or folder doesn’t exist.

if (client.Files.FileExists("/some_file.txt")) // check if the file exists
{
        FileMetadata fileMetadata = await client.Files.GetMetadata("/some_file.txt"); // get the file's metadata
}

if (client.Files.FolderExists("/some_folder")) // check if the folder exists
{
        FolderMetadata folderMetadata = await client.Files.GetMetadata("/some_folder"); // get the folder's metadata
}

It is important to note that all paths should start with a forwardslash (/) except if you are referencing the root directory, where you leave the path blank.

File operations¶

Copying and moving files¶

Coming soon!

Users.GetAccount Method (string)¶

Get information about a user’s account.

Syntax¶

Users.GetAccount(string accountId)

Parameters¶

accountId: System.String A user’s account identifier.

Returns¶

DotNetBox.BasicAccount Basic information about the specified account.

Users.GetAccountBatch Method (string[])¶

Get information about multiple user accounts. At most 300 accounts may be queried per request.

Syntax¶

Users.GetAccountBatch(string[] accountIds)

Parameters¶

accountIds: System.String[] List of user account identifiers. Should not contain any duplicate account IDs.

Returns¶

DotNetBox.BasicAccount[] List of basic information about every account.

Users.GetCurrentAccount Method¶

Get information about the current user’s account.

Syntax¶

Users.GetCurrentAccount()

Returns¶

DotNetBox.FullAccount Detailed information about the current user’s account.

Users.GetSpaceUsage Method¶

Get the space usage information for the current user’s account.

Syntax¶

Users.GetSpaceUsage()

Returns¶

DotNetBox.SpaceUsage Information about the user’s space usage and quota.

Files.Cancel Method¶

Cancel the current asynchronous operation.

Syntax¶

Files.Cancel()

Files.Copy Method (string, string)¶

Copy a file or folder to a different location in the user’s Dropbox. If the source path is a folder, all its contents will be copied.

Syntax¶

Files.Copy(string fromPath, string toPath)

Parameters¶

fromPath: System.String Path in the user’s Dropbox to be copied or moved.
toPath: System.String Path in the user’s Dropbox that is the destination.

Returns¶

DotNetBox.Metadata Metadata of the copied (destination) file.

Files.CreateFolder Method (string)¶

Create a folder at a given path.

Syntax¶

Files.CreateFolder(string path)

Parameters¶

path: System.String Path in the user’s Dropbox to create.

Returns¶

DotNetBox.FolderMetadata Metadata of the newly created folder.

Files.Delete Method (string)¶

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too.

Syntax¶

Files.Delete(string path)

Parameters¶

path: System.String Path in the user’s Dropbox to delete.

Returns¶

DotNetBox.Metadata Metadata of the deleted file or folder.

Files.Download Method (string, string)¶

Download a file from a user’s

Syntax¶

Files.Download(string path, string savePath)

Parameters¶

path: System.String The path of the file to download.
savePath: System.String The path to where the file will be saved.

Returns¶

DotNetBox.FileMetadata Metadata of the downloaded file.

Files.FileExists Method (string)¶

Checks whether a file exists or not.

Syntax¶

Files.FileExists(string path)

Parameters¶

path: System.String Path of the file.

Returns¶

System.Boolean Whether the file exists or not.

Files.FolderExists Method (string)¶

Checks whether a folder exists or not.

Syntax¶

Files.FolderExists(string path)

Parameters¶

path: System.String Path of the folder.

Returns¶

System.Boolean Whether the folder exists or not.

Files.GetMetadata Method (string, bool)¶

Returns the metadata for a file or folder.

Syntax¶

Files.GetMetadata(string path, bool includeMediaInfo)

Parameters¶

path: System.String The path of a file or folder onCan also be a rev or id.
includeMediaInfo: System.Boolean If true, FileMetadata.MediaInfo is set for photo and video. The default for this field is False.

Returns¶

DotNetBox.Metadata Metadata for a file or folder. It will be of type FileMetadata, FolderMetadata, or DeletedMetadata

Files.GetPreview Method (string, string)¶

Get a preview for a file in PDF format. Currently previews are only generated for the files with the following extensions: .doc, .docx, .docm, .ppt, .pps, .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf

Syntax¶

Files.GetPreview(string path, string savePath)

Parameters¶

path: System.String The path of the file to preview.
savePath: System.String Path at which to save the preview file.

Returns¶

DotNetBox.FileMetadata Metadata of the file of which a preview was made.

Files.GetThumbnail Method (string, string, ThumbnailFormat, ThumbnailSize)¶

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.

Syntax¶

Files.GetThumbnail(string path, string savePath, ThumbnailFormat format, ThumbnailSize size)

Parameters¶

path: System.String The path to the image file you want to thumbnail.
savePath: System.String The path at which to save the thumbnail image.
format: DotNetBox.ThumbnailFormat The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts.
size: DotNetBox.ThumbnailSize The size for the thumbnail image.

Returns¶

DotNetBox.FileMetadata Metadata of the file of which a thumbnail was made.

Files.ListFolder Method (string, bool, bool, bool)¶

Returns the contents of a folder.

Syntax¶

Files.ListFolder(string path, bool recursive, bool includeMediaInfo, bool includeDeleted)

Parameters¶

path: System.String The path to the folder you want to see the contents of.
recursive: System.Boolean If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. The default for this field is False.
includeMediaInfo: System.Boolean If true, FileMetadata.MediaInfo is set for photo and video. The default for this field is False.
includeDeleted: System.Boolean If true, the results will include entries for files and folders that used to exist but were deleted. The default for this field is False.

Returns¶

DotNetBox.ListFolderResult Contents of folder.

Files.ListFolderContinue Method (string)¶

Once a cursor has been retrieved from ListFolder, use this to paginate through all files and retrieve updates to the folder.

Syntax¶

Files.ListFolderContinue(string cursor)

Parameters¶

cursor: System.String The cursor returned by your last call to ListFolder or ListFolderContinue.

Returns¶

DotNetBox.ListFolderResult Contents of folder.

Files.ListFolderGetLatestCursor Method (string, bool, bool, bool)¶

A way to quickly get a cursor for the folder’s state. Unlike ListFolder, ListFolderGetLatestCursor doesn’t return any entries. This endpoint is for apps which only needs to know about new files and modifications and doesn’t need to know about files that already exist in the folder.

Syntax¶

Files.ListFolderGetLatestCursor(string path, bool recursive, bool includeMediaInfo, bool includeDeleted)

Parameters¶

path: System.String The path to the folder you want to see the contents of.
recursive: System.Boolean If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. The default for this field is False.
includeMediaInfo: System.Boolean If true, FileMetadata.MediaInfo is set for photo and video. The default for this field is False.
includeDeleted: System.Boolean If true, the results will include entries for files and folders that used to exist but were deleted. The default for this field is False.

Returns¶

System.String Pass the cursor into ListFolderContinue to see what’s changed in the folder since your previous query.

Files.ListFolderLongpoll Method (string, int)¶

A longpoll endpoint to wait for changes on an account. In conjunction with list_folder, this call gives you a low-latency way to monitor an account for file changes. The connection will block until there are changes available or a timeout occurs.

Syntax¶

Files.ListFolderLongpoll(string cursor, int timeout)

Parameters¶

cursor: System.String A cursor as returned by ListFolder or ListFolderContinue
timeout: System.Int32 A timeout in seconds. The request will block for at most this length of time, plus up to 90 seconds of random jitter added to avoid the thundering herd problem. Care should be taken when using this parameter, as some network infrastructure does not support long timeouts. The default for this field is 30.

Returns¶

DotNetBox.ListFolderLongpollResult Whether files have been changed or not.

Files.ListRevisions Method (string, int)¶

Returns revisions of a file.

Syntax¶

Files.ListRevisions(string path, int limit)

Parameters¶

path: System.String The path to the file you want to see the revisions of.
limit: System.Int32 The maximum number of revision entries returned. The default for this field is 10.

Returns¶

DotNetBox.ListRevisionsResult List of revisions applied to the file.

Files.Move Method (string, string)¶

Move a file or folder to a different location in the user’s Dropbox. If the source path is a folder, all its contents will be moved.

Syntax¶

Files.Move(string fromPath, string toPath)

Parameters¶

fromPath: System.String Path in the user’s Dropbox to be copied or moved.
toPath: System.String Path in the user’s Dropbox that is the destination.

Returns¶

DotNetBox.Metadata Metadata of the moved file.

Files.PermanentlyDelete Method (string)¶

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too.

Syntax¶

Files.PermanentlyDelete(string path)

Parameters¶

path: System.String Path in the user’s Dropbox to delete.

Returns¶

DotNetBox.Metadata Metadata of the deleted file or folder.

Files.Restore Method (string, string)¶

Restore a file to a specific revision.

Syntax¶

Files.Restore(string path, string rev)

Parameters¶

path: System.String The path to the file you want to restore.
rev: System.String The revision to restore for the file. Defaults to previous revision.

Returns¶

DotNetBox.FileMetadata Metadata of the restored file.

Files.Search Method (string, string, int, int, SearchMode)¶

Searches for files and folders.

Syntax¶

Files.Search(string path, string query, int start, int maxResults, SearchMode mode)

Parameters¶

path: System.String The path in the user’s Dropbox to search. Should probably be a folder.
query: System.String The string to search for. The search string is split on spaces into multiple tokens. For file name searching, the last token is used for prefix matching.
start: System.Int32 The starting index within the search results (used for paging). The default for this field is 0.
maxResults: System.Int32 The maximum number of search results to return. The default for this field is 100.
mode: DotNetBox.SearchMode The search mode (Filename, FilenameAndContent, or DeletedFilename). Note that searching file content is only available for Dropbox Business accounts.

Returns¶

DotNetBox.SearchResult Files and folders that match the search query.

Files.Upload Method (string, string, WriteMode, bool, bool, string)¶

Create a new file with the contents provided in the request asynchronously.

Syntax¶

Files.Upload(string filePath, string path, WriteMode mode, bool autorename, bool mute, string rev)

Parameters¶

filePath: System.String Path to the file to upload.
path: System.String Path in the user’s Dropbox to save the file.
mode: DotNetBox.WriteMode Selects what to do if the file already exists.
autorename: System.Boolean If there’s a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict. The default for this field is False.
mute: System.Boolean Normally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If True, this tells the clients that this modification shouldn’t result in a user notification. The default for this field is False.
rev: System.String Overwrite if the given “rev” matches the existing file’s “rev”. The autorename strategy is to append the string “conflicted copy” to the file name. Only applies if WriteMode is Update.