search

citrix / ShareFile-NET

C# library for accessing ShareFile V3 API
MIT License
36 stars 26 forks source link

readme

ShareFile Client SDK Documentation

Before continuing please familiarize yourself with the API and it's methodology at https://api.sharefile.com/rest

If you would like to download the Nuget Package for this SDK, you can find it here https://www.nuget.org/packages/ShareFile.Api.Client/

License

All code is licensed under the MIT License.

Tooling requirements

Definitions

Authentication

Authentication with ShareFile v3 API makes use of OAuth 2.0 protocol. Some helper methods and classes are provided to make authentication easier for consumers.

ShareFile Basics

Once authenticated, getting information from ShareFile is pretty easy.
Below are some samples on what you can do, it assumes there is an instance of ShareFileClient - sfClient available.

Start a Session

  var session = await sfClient.Session.Login().ExecuteAsync();

End session

  var session = await sfClient.Session.Logout().ExecuteAsync();

  // Should clean up credentials and cookies if you plan to
  // re-use the sfClient instance.
  sfClient.ClearCredentialsAndCookies();

Get the current user

A User in ShareFile derives from the Principal object. For most consumers you will be interested in User and AccountUser. The AccountUser type designates the user to be an Employee and will have some additional properties available.
You can also use User.IsEmployee(), to get the additional properties you will still need to cast the instance to AccountUser

  var user = await sfClient.Users.Get().ExecuteAsync();

Get the default folder for a User

This call will return the default folder for the currently authenticated User.

  var folder = (Folder) await sfClient.Items.Get().ExecuteAsync();

Get the contents of a folder

  var folderContents = await sfClient.Items.GetChildren(folder.url).ExecuteAsync();

  // will have the contents an ODataFeed<Item>
  // the Feed property will be a List<Item>

  // operate over the feed
  folderContents.Feed

Create a Folder

  var parentFolder = (Folder) await sfClient.Items.Get().ExecuteAsync();

  var newFolder = new Folder
  {
    Name = "New Folder 1"
  };

  newFolder = await sfClient.Items.CreateFolder(parentFolder.url, newFolder).ExecuteAsync();

Search

  var searchResults = await sfClient.Items.Search("query").ExecuteAsync();

To browse search results (currently, there is no Uri returned that points to the Item):

  var itemUri = sfClient.Items.GetAlias(searchResult.ItemID);
  var item = await sfClient.Items.Get(itemUri).ExecuteAsync();

Access Aliased Folders

There are some folders within ShareFile that are not easily discovered, however the SDK can help you find them. These aliases are exposed on an enum ItemAlias.

  var itemUri = sfClient.Items.GetAlias(ItemAlias.Top);
  var item = await sfClient.Items.Get(itemUri).ExecuteAsync();

Upload/Download

Download

  var downloader = sfClient.GetAsyncFileDownloader(itemToDownload);
  using(var fileStream = File.Open(@"C:\test\newImage.png", FileMode.OpenOrCreate))
  {
    await downloader.DownloadToAsync(fileStream);
  }

Upload

  var parentFolder = (Folder) await sfClient.Items.Get().ExecuteAsync();
  using(var file = File.Open(@"C:\test\image.png", FileMode.OpenOrCreate))
  {
    var uploadRequest = new UploadSpecificationRequest
    {
      FileName = file.Name,
      FileSize = file.Length,
      Details = "Sample details",
      Parent = parentFolder.url
    };

    var uploader = sfClient.GetAsyncFileUploader(uploadRequest, file);

    var uploadResponse = await uploader.UploadAsync();
  }

ShareFile supports a concept called Shares which are labeled as Request and Send. If you have a Request Share, you can fulfill the request by uploading directly to it via the SDK.

  // Assumes you have a Share object or at least a Uri to a Share
  using(var file = File.Open(@"C:\test\image.png", FileMode.OpenOrCreate))
  {
    var uploadRequest = new UploadSpecificationRequest
    {
      FileName = file.Name,
      FileSize = file.Length,
      Details = "Sample details",
      Parent = shareUri
    };

    var uploader = sfClient.GetAsyncFileUploader(uploadRequest, file);

    var uploadResponse = await uploader.UploadAsync();
  }

Get transfer progress

On any transfer you can be notified of progress. On the instance of the uploader/downloader you can provide a delegate to OnTransferProgress.

Deleting Items

Delete a specific version of a file

await sfClient.Items.Delete(file.url).ExecuteAsync();

Delete a folder

await sfClient.Items.Delete(folder.url).ExecuteAsync();

Delete all versions of a file

Accessing a Share

Assuming you have the url that points to the Share API resource (ex. https://subdomain.sharefile.com/sf/v3/Shares(s0123456789)), you can easily access the Items shared. Depending on the share you may be required to already be authenticated.

var shareUri = new Uri("https://subdomain.sharefile.com/sf/v3/Shares(s0123456789)");
var share = await sfClient.Shares.Get(shareUri);
var shareItems = await sfClient.Shares.GetItems(shareUri, share.AliasID);

Items associated with a Share cannot be downloaded as you normally might, instead you need to use the Shares API to download.

// assuming you already have shareItems as noted before

var fileStream = await sfClient.Shares.Download(shareUri, share.AliasID, shareItems.Select(x => x.Id).First());

Leveraging oData

ShareFile supports the oData protocol which provides standard ways of handling common tasks such as:

Select

The following Query will only select the Name property. If you execute this, all other properties will be their default values. This is convenient for reducing payloads on the wire.

  var folder = (Folder) await sfClient.Items.Get()
                .Select("Name")
                .ExecuteAsync();

Expand

The following Query will expand Children. Since we know we are querying for a Folder we can ask ShareFile to go ahead and return the list of Children. This helps reduce the number of round trips required. Note Chlidren is presented as a List<Item> instead of an ODataFeed<Item>.

  var folder = (Folder) await sfClient.Items.Get()
                .Expand("Children")
                .ExecuteAsync();

  // Is now populated.
  folder.Children

Top/Skip

When working with ODataFeed responses, you can limit the size of the response by using Top and Skip. The following Query will return up to 10 Children and skip the first 10.

  var folderContents = await sfClient.Items.GetChildren()
                        .Top(10)
                        .Skip(10)
                        .ExecuteAsync();

To support paging ODataFeed will also return a nextLink which will compute the Top and Skip values for you.