IFilesClient
Namespace: Meshmakers.Octo.Sdk.ServiceClient.AssetRepositoryServices.Files
Typed client of the platform file system of a tenant (System.Files, AB#6171 / AB#6229).
public interface IFilesClient
Remarks:
Bytes go over REST ({assetServices}/{tenant}/v1/files): upload, download, zip, statistics,
capabilities. Metadata — roots, listings, create folder, rename, move, delete — goes over the
tenant's generic GraphQL endpoint (tenants/{tenant}/GraphQL, System.Files types), as decided
for the platform (design Q1). Both carry the client's bearer token; access is the caller's data
permissions, only IFilesClient.CreateRootAsync(String, String, CancellationToken) needs the FileManagement role.
Paths are '/'-separated below a root addressed by its well-known name (default root Files).
Every segment is URL-encoded on its own; '.' and '..' segments are refused client-side with an
ArgumentException. Server errors throw FilesApiException with the stable
code (FileErrorCodes); 401 throws UnauthorizedServiceAccessException.
Methods
GetCapabilitiesAsync(CancellationToken)
Limits and features of the file API of the cluster.
Task<FilesCapabilitiesDto> GetCapabilitiesAsync(CancellationToken cancellationToken)
Parameters
cancellationToken CancellationToken
Returns
UploadAsync(String, String, Stream, String, FileConflictMode, Boolean, CancellationToken)
Uploads a file by path (PUT {root}/{folders…}/{name}, raw body).
Task<FileEntryDto> UploadAsync(string root, string path, Stream content, string contentType, FileConflictMode conflict, bool createFolders, CancellationToken cancellationToken)
Parameters
root String
Well-known name of the folder root
path String
Path below the root, ending with the file name
content Stream
Content; streamed, the length is sent when the stream is seekable
contentType String
Content type; null lets the server derive it from the name
conflict FileConflictMode
What to do when the name exists
createFolders Boolean
Create missing folders on the way (otherwise 404 PATH_NOT_FOUND)
cancellationToken CancellationToken
Cancellation token
Returns
Task<FileEntryDto>
The stored file; FileEntryDto.Replaced is true when existing content was replaced
UploadToFolderAsync(String, String, Stream, String, FileConflictMode, CancellationToken)
Uploads a file into the folder or root addressed by rtId (POST items/{rtId}/content?name=).
Task<FileEntryDto> UploadToFolderAsync(string folderRtId, string name, Stream content, string contentType, FileConflictMode conflict, CancellationToken cancellationToken)
Parameters
folderRtId String
name String
content Stream
contentType String
conflict FileConflictMode
cancellationToken CancellationToken
Returns
ReplaceContentAsync(String, Stream, String, CancellationToken)
Replaces the content of the file addressed by rtId; rtId and links stay
(PUT items/{rtId}/content).
Task<FileEntryDto> ReplaceContentAsync(string fileRtId, Stream content, string contentType, CancellationToken cancellationToken)
Parameters
fileRtId String
content Stream
contentType String
cancellationToken CancellationToken
Returns
DownloadAsync(String, String, Boolean, CancellationToken)
Downloads a file by path. Dispose the result.
Task<FileDownload> DownloadAsync(string root, string path, bool inline, CancellationToken cancellationToken)
Parameters
root String
Well-known name of the folder root
path String
Path of the file below the root
inline Boolean
Ask for inline delivery (only changes the Content-Disposition type)
cancellationToken CancellationToken
Cancellation token
Returns
DownloadByIdAsync(String, Boolean, CancellationToken)
Downloads a file by rtId. Dispose the result.
Task<FileDownload> DownloadByIdAsync(string fileRtId, bool inline, CancellationToken cancellationToken)
Parameters
fileRtId String
inline Boolean
cancellationToken CancellationToken
Returns
DownloadZipAsync(ZipRequestDto, CancellationToken)
Streamed zip of files and folders (folders recursively). Limits are checked by the server before the first byte (413 LIMIT_EXCEEDED). Dispose the result.
Task<FileDownload> DownloadZipAsync(ZipRequestDto request, CancellationToken cancellationToken)
Parameters
request ZipRequestDto
cancellationToken CancellationToken
Returns
DownloadZipAsync(IEnumerable<String>, String, CancellationToken)
Streamed zip of the entries with the given rtIds. Dispose the result.
Task<FileDownload> DownloadZipAsync(IEnumerable<string> rtIds, string fileName, CancellationToken cancellationToken)
Parameters
rtIds IEnumerable<String>
fileName String
cancellationToken CancellationToken
Returns
GetFolderStatsAsync(String, String, CancellationToken)
Deep statistics of a root (path empty) or folder addressed by path.
Task<FolderStatsDto> GetFolderStatsAsync(string root, string path, CancellationToken cancellationToken)
Parameters
root String
path String
cancellationToken CancellationToken
Returns
GetFolderStatsByIdAsync(String, CancellationToken)
Deep statistics of a root or folder addressed by rtId.
Task<FolderStatsDto> GetFolderStatsByIdAsync(string folderRtId, CancellationToken cancellationToken)
Parameters
folderRtId String
cancellationToken CancellationToken
Returns
GetLinkedCountsAsync(IEnumerable<String>, CancellationToken)
Number of links per entry to other entities: every association except System/ParentChild, any
role and direction (POST linked-counts). Entries the caller cannot see are missing from the
result. More than 500 rtIds are sent in batches of 500.
Task<IReadOnlyDictionary<string, int>> GetLinkedCountsAsync(IEnumerable<string> rtIds, CancellationToken cancellationToken)
Parameters
rtIds IEnumerable<String>
cancellationToken CancellationToken
Returns
Task<IReadOnlyDictionary<String, Int32>>
ListRootsAsync(Int32, String, CancellationToken)
Lists the folder roots visible to the caller, sorted by name.
Task<FilesPage> ListRootsAsync(int first, string after, CancellationToken cancellationToken)
Parameters
first Int32
after String
cancellationToken CancellationToken
Returns
GetEntryAsync(String, String, CancellationToken)
Resolves an entry by path (empty path = the root itself). Names match case-insensitively, an exact match wins; throws ROOT_NOT_FOUND / PATH_NOT_FOUND / AMBIGUOUS_PATH like the REST API.
Task<FileEntryDto> GetEntryAsync(string root, string path, CancellationToken cancellationToken)
Parameters
root String
path String
cancellationToken CancellationToken
Returns
GetEntryByIdAsync(String, CancellationToken)
An entry by rtId (with its parent rtId), or null when it does not exist or is hidden.
Task<FileEntryDto> GetEntryByIdAsync(string rtId, CancellationToken cancellationToken)
Parameters
rtId String
cancellationToken CancellationToken
Returns
ListChildrenAsync(String, String, Int32, String, CancellationToken)
Lists the direct children (folders and files, sorted by name) of a root or folder addressed by path.
Task<FilesPage> ListChildrenAsync(string root, string path, int first, string after, CancellationToken cancellationToken)
Parameters
root String
path String
first Int32
after String
cancellationToken CancellationToken
Returns
ListChildrenByIdAsync(String, Int32, String, CancellationToken)
Lists the direct children (folders and files, sorted by name) of a root or folder addressed by rtId.
Task<FilesPage> ListChildrenByIdAsync(string folderRtId, int first, string after, CancellationToken cancellationToken)
Parameters
folderRtId String
first Int32
after String
cancellationToken CancellationToken
Returns
CreateRootAsync(String, String, CancellationToken)
Creates a folder root. Requires the FileManagement role (else FORBIDDEN); the well-known
name must be unique (NAME_CONFLICT) and not reserved (RESERVED_NAME).
Task<FileEntryDto> CreateRootAsync(string name, string wellKnownName, CancellationToken cancellationToken)
Parameters
name String
wellKnownName String
cancellationToken CancellationToken
Returns
CreateFolderAsync(String, String, String, CancellationToken)
Creates a folder below the root or folder addressed by path (parentPath empty =
directly in the root).
Task<FileEntryDto> CreateFolderAsync(string root, string parentPath, string name, CancellationToken cancellationToken)
Parameters
root String
parentPath String
name String
cancellationToken CancellationToken
Returns
CreateFolderInAsync(String, String, CancellationToken)
Creates a folder below the root or folder addressed by rtId.
Task<FileEntryDto> CreateFolderInAsync(string parentRtId, string name, CancellationToken cancellationToken)
Parameters
parentRtId String
name String
cancellationToken CancellationToken
Returns
RenameAsync(String, String, CancellationToken)
Renames a root, folder or file. Service-owned and blueprint roots answer PROTECTED_ROOT.
Task RenameAsync(string rtId, string newName, CancellationToken cancellationToken)
Parameters
rtId String
newName String
cancellationToken CancellationToken
Returns
MoveAsync(String, String, CancellationToken)
Moves a folder or file into another root or folder. A folder cannot move into itself or below itself (MOVE_INTO_ITSELF); the name must be free in the target (NAME_CONFLICT).
Task MoveAsync(string rtId, string targetFolderRtId, CancellationToken cancellationToken)
Parameters
rtId String
targetFolderRtId String
cancellationToken CancellationToken
Returns
Remarks:
One mutation that DELETEs the link to the current parent and CREATEs the link to the target (the server enforces one parent per entry, INVALID_REQUEST otherwise). Only the first parent the entry reports is deleted; a legacy entry with several parents keeps the others and the server refuses the move.
DeleteAsync(String, CancellationToken)
Deletes a root, folder or file. Roots and folders are deleted recursively by the server, all or nothing: when the caller may not delete any entry below, nothing is deleted. Check IFilesClient.GetDeleteImpactAsync(String, CancellationToken) first. Above the server's delete cap (MaxDeleteEntries, default 2,000 entries) the delete is refused with LIMIT_EXCEEDED (status 409).
Task DeleteAsync(string rtId, CancellationToken cancellationToken)
Parameters
rtId String
cancellationToken CancellationToken
Returns
GetDeleteImpactAsync(String, CancellationToken)
What a delete of the entry would take with it: for roots and folders the deep statistics (counts, bytes, linked files with samples of their linked entities, entries hidden by data permissions); for a file its number of links (DeleteImpactDto.LinkedCount, via linked-counts).
Task<DeleteImpactDto> GetDeleteImpactAsync(string rtId, CancellationToken cancellationToken)
Parameters
rtId String
cancellationToken CancellationToken