File Sharing API for C# SDK

Allows users to upload and share files. You can upload any file of up to 5 MB in size. This feature is commonly used in social apps to share images, or in medical apps to share medical records for patients.

When a file is uploaded on a channel, it's stored and managed using a storage service, and associated with your key. Subscribers to that channel receive a file event which contains a file ID, filename, and optional description.

Request execution

We recommend using try and catch statements when working with the C# SDK.

If there's an issue with the provided API parameter values, like missing a required parameter, the SDK throws an exception. However, if there is a server-side API execution issue or a network problem, the error details are contained within the status.

try
{
PNResult<PNPublishResult> publishResponse = await pubnub.Publish()
.Message("Why do Java developers wear glasses? Because they can't C#.")
.Channel("my_channel")
.ExecuteAsync();

PNStatus status = publishResponse.Status;

Console.WriteLine("Server status code : " + status.StatusCode.ToString());
}
catch (Exception ex)
{
Console.WriteLine($"Request can't be executed due to error: {ex.Message}");
}

Send file

Upload the file to a specified channel.

This method covers the entire process of sending a file, including preparation, uploading the file to a cloud storage service, and post-uploading messaging on a channel.

For the last messaging step, SendFile internally calls the PublishFileMessage method to publish a message on the channel.

The published message contains metadata about the file, such as the file identifier and name, enabling others on the channel to find out about the file and access it.

Method(s)

pubnub.SendFile()
.Channel(string)
.File(string|byte[])
.FileName(string)
.Message(string)
.ShouldStore(bool)
.Meta(Dictionary<string, object>)
.Ttl(int)
.CustomMessageType(string)
* required
ParameterDescription
Channel *
Type: string
Channel for the file.
File *
Type: string or byte[]
Full path of the file with file name or an array of bytes.
When using an array of bytes, you must set FileName.
FileName
Type: string
Name of the file to send. You can use it to override the default file name.
Message
Type: string
Message which should be sent along with file to specified channel.
ShouldStore
Type: bool
Whether PubNub published file message should be stored in channel history.
Meta
Type: Dictionary<string, object>
Dictionary<string, object> with values which should be used by PubNub service to filter file messages.
TtL
Type: int
How long message should be stored in channel's storage.
CustomMessageType
Type: string
A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes - and underscores _ are allowed. The value cannot start with special characters or the string pn_ or pn-.

Examples: text, action, poll.
Deprecated parameter

The CipherKey parameter in this method is deprecated. We recommend that you configure the crypto module on your PubNub instance instead.

If you pass CipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Basic Usage

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

using System;
using System.Threading.Tasks;
using PubnubApi;

class SendFileExample
{
static async Task Main(string[] args)
{
PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId"))
{
SubscribeKey = "demo",
PublishKey = "demo",
Secure = true
};

show all 44 lines

Response

{
"Timetoken":15957709330808500,
"FileId":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
"FileName":"cat_picture.jpg"
}

Returns

The SendFile() operation returns a PNResult``<PNFileUploadResult> which contains the following properties:

Property NameTypeDescription
Result
PNFileUploadResult
Returns a PNFileUploadResult object.
Status
PNStatus
Returns a PNStatus object.

PNFileUploadResult contains the following properties:

Property NameTypeDescription
Timetoken
long
Returns a PNFileUploadResult object.
FileId
string
Returns the ID of the file.
FileName
string
Returns the name of the file.

List channel files

Retrieve list of files uploaded to Channel.

Method(s)

pubnub.ListFiles()
.Channel(string)
* required
ParameterDescription
Channel *
Type: string
Default:
n/a
Channel to get list of files.
Limit
Type: int
Default:
100
Number of files to return.
Next
Type: string
Default:
n/a
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.

Basic Usage

PNResult<PNListFilesResult> listFilesResponse = await pubnub.ListFiles()
.Channel("my_channel")
.ExecuteAsync();
PNListFilesResult listFilesResult = listFilesResponse.Result;
PNStatus listFilesStatus = listFilesResponse.Status;
if (!listFilesStatus.Error && listFilesResult != null)
{
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(listFilesResult));
}
else
{
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(listFilesStatus));
}

Response

{
"FilesList":[
{
"Name":"cat_picture.jpg",
"Id":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
"Size":25778,
"Created":"2020-07-26T13:42:06Z"
}],
"Count":1,
"Next":null
}

Returns

The ListFiles() operation returns a PNResult<PNListFilesResult> which contains the following properties:

Property NameTypeDescription
Result
PNListFilesResult
Returns a PNListFilesResult object.
Status
PNStatus
Returns a PNStatus object.

PNListFilesResult contains the following properties:

Property NameTypeDescription
FilesList
list<PNFileResult>
List of channel files.
Count
int
Number of files returned.
Next
string
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.

PNFileResult contains the following properties:

Property NameTypeDescription
Name
string
Name of the file.
Id
string
ID of the file.
Size
int
Size of the file.
Created
string
Create date of the file.

Get File Url

Generate URL which can be used to download file from target Channel.

Method(s)

pubnub.GetFileUrl()
.Channel(string)
.FileId(string)
.FileName(string)
* required
ParameterDescription
Channel *
Type: string
Name of channel within which file with name has been uploaded.
FileId *
Type: string
Unique file identifier which has been assigned during file upload.
FileName *
Type: string
Name under which uploaded file is stored for channel.

Basic Usage

PNResult<PNFileUrlResult> getFileUrlResponse = await pubnub.GetFileUrl()
.Channel("my_channel")
.FileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
.FileName("cat_picture.jpg")
.ExecuteAsync();
PNFileUrlResult getFileUrlResult = getFileUrlResponse.Result;
PNStatus getFileUrlStatus = getFileUrlResponse.Status;
if (!getFileUrlStatus.Error && getFileUrlResult != null)
{
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(getFileUrlResult));
}
else
{
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(getFileUrlStatus));
}

Response

{
"Url":"http://ps.pndsn.com/v1/files/demo/channels/my_channel/files/d9515cb7-48a7-41a4-9284-f4bf331bc770/cat_picture.jpg?pnsdk=NET461CSharp4.9.0.0&timestamp=1595771548&uuid=pn-9ce9e988-8e04-40bf-90c4-ebe170478f7d"
}

Returns

The GetFileUrl() operation returns a PNResult<PNFileUrlResult> which contains the following properties:

Property NameTypeDescription
Result
PNFileUrlResult
Returns a PNFileUrlResult object.
Status
PNStatus
Returns a PNStatus object.

PNFileUrlResult contains the following properties:

Property NameTypeDescription
Url
string
URL which can be used to download remote file with specified name and identifier.

Download file

Download file from specified Channel.

Method(s)

pubnub.DownloadFile()
.Channel(string)
.FileId(string)
.FileName(string)
* required
ParameterDescription
Channel *
Type: string
Name of channel within which file with name has been uploaded.
FileId *
Type: string
Unique file identifier which has been assigned during file upload.
FileName *
Type: string
Name under which uploaded file is stored for channel.
Deprecated parameter

The CipherKey parameter in this method is deprecated. We recommend that you configure the crypto module on your PubNub instance instead.

If you pass CipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Basic Usage

PNResult<PNDownloadFileResult> fileDownloadResponse = await pubnub.DownloadFile()
.Channel("my_channel")
.FileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
.FileName("cat_picture.jpg")
.ExecuteAsync();
PNDownloadFileResult fileDownloadResult = fileDownloadResponse.Result;
PNStatus fileDownloadStatus = fileDownloadResponse.Status;
if (!fileDownloadStatus.Error && fileDownloadResult != null)
{
fileDownloadResult.SaveFileToLocal(downloadUrlFileName); //saves to bin folder if no path is provided
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(fileDownloadResult.FileName));
}
else
{
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(fileDownloadStatus));
show all 16 lines

Response

{
//Call fileDownloadResult.SaveFileToLocal(<destination path>) to save file.
"FileBytes":"/9j/4AAQSkZJRgABAQEAkACQAAD/4RCERXhpZgAATU0AKgAAAAgABAE7AAIAAAAGAAAISodpAAQAAAABAAAIUJydAAEAAAA...<truncated due to lengthy data",
"FileName":"cat_picture.jpg"
}

Returns

The DownloadFile() operation returns a PNResult<PNDownloadFileResult> which contains the following properties:

Property NameTypeDescription
Result
PNDownloadFileResult
Returns a PNDownloadFileResult object.
Status
PNStatus
Returns a PNStatus object.

PNDownloadFileResult contains the following properties:

Property NameTypeDescription
FileBytes
byte[]
byte array of the downloaded file. Use SaveFileToLocal method to copy file to local.
FileName
string
Name of the downloaded file from channel.
SaveFileToLocal(string)
Provide full destination path to SaveFileToLocal for saving the downloaded file locally.

Delete file

Delete file from specified Channel.

Method(s)

pubnub.DeleteFile()
.Channel(string)
.FileId(string)
.FileName(string)
* required
ParameterDescription
Channel *
Type: string
Name of channel within which file with name needs to be deleted.
FileId *
Type: string
Unique file identifier of the file to be deleted.
FileName *
Type: string
Name of the file to be deleted from the channel.

Basic Usage

PNResult<PNDeleteFileResult> deleteFileResponse = await pubnub.DeleteFile()
.Channel("my_channel")
.FileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
.FileName("cat_picture.jpg")
.ExecuteAsync();
PNDeleteFileResult deleteFileResult = deleteFileResponse.Result;
PNStatus deleteFileStatus = deleteFileResponse.Status;
if (!deleteFileStatus.Error && deleteFileResult != null)
{
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(deleteFileResult));
}
else
{
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(deleteFileStatus));
}

Response

{}

Returns

The DeleteFile() operation returns a PNResult<PNDeleteFileResult> which contains the following properties:

Property NameTypeDescription
Result
PNDeleteFileResult
Returns a PNDeleteFileResult object.
Status
PNStatus
Returns a PNStatus object.

PNDeleteFileResult returns empty object

Publish file message

Publish the uploaded file message to a specified channel.

This method is called internally by SendFile as part of the file-sending process to publish the message with the file (already uploaded in a storage service) on a channel.

This message includes the file's unique identifier and name elements, which are needed to construct download links and inform channel subscribers that the file is available for download.

You can call this method when SendFile fails and returns the status.operation === PNPublishFileMessageOperation error. In that case, you can use the data from the status object to try again and use PublishFileMessage to manually resend a file message to a channel without repeating the upload step.

Method(s)

pubnub.PublishFileMessage()
.Channel(string)
.FileId(string)
.FileName(string)
.Message(object)
.Meta(Dictionary<string, object>)
.ShouldStore(bool)
.CustomMessageType(string)
* required
ParameterDescription
Channel *
Type: string
Default:
n/a
Name of channel to publish file message
FileId *
Type: string
Default:
n/a
Unique file identifier of the file.
FileName *
Type: string
Default:
n/a
Name of the file.
Message
Type: string
Default:
n/a
The payload.
Meta
Type: string
Default:
n/a
Meta data object which can be used with the filtering ability.
ShouldStore
Type: bool
Default:
true
Store in history.
CustomMessageType
Type: string
Default:
n/a
A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes - and underscores _ are allowed. The value cannot start with special characters or the string pn_ or pn-.

Examples: text, action, poll.

Basic Usage

PNResult<PNPublishFileMessageResult> publishFileMsgResponse = await pubnub.PublishFileMessage()
.Channel("my_channel")
.FileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
.FileName("cat_picture.jpg") //checks the bin folder if no path is provided
.Message("This is a sample message")
.CustomMessageType("file-message")
.ExecuteAsync();
PNPublishFileMessageResult publishFileMsgResult = publishFileMsgResponse.Result;
PNStatus publishFileMsgStatus = publishFileMsgResponse.Status;
if (!publishFileMsgStatus.Error && publishFileMsgResult != null)
{
Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(publishFileMsgResult));
}
else
{
show all 17 lines

Response

{
"Timetoken":15957738720237858
}

Returns

The PublishFileMessage() operation returns a PNResult<PNPublishFileMessageResult> which contains the following properties:

Property NameTypeDescription
Result
PNPublishFileMessageResult
Returns a PNPublishFileMessageResult object.
Status
PNStatus
Returns a PNStatus object.

PNPublishFileMessageResult contains the following properties:

Property NameTypeDescription
Timetoken
long
Returns a long representation of the timetoken when the message was published.
Last updated on