Share via


File.StartUpload method

Starts a new chunk upload session and uploads the first fragment. The current file content is not changed when this method completes. The method is idempotent (and therefore does not change the result) as long as you use the same values for uploadId and stream.

The upload session ends either when you use the CancelUpload(Guid) method or when you successfully complete the upload session by passing the rest of the file contents through the ContinueUpload(Guid, Int64, Stream) and FinishUpload(Guid, Int64, Stream) methods.

For example, you can pass a 35 MB file by dividing it into three 10 MB streams and one 5 MB stream and uploading them this way (using the resulting offset values of 10, 20 and 30 MB):

StartUpload(GUID, stream1)
ContinueUpload(GUID, 10 MB, stream2)
ContinueUpload(GUID, 20 MB, stream3)
FinishUpload(GUID, 30 MB, stream4)

The StartUpload(Guid, Stream) and ContinueUpload(Guid, Int64, Stream) methods return the size of the running total of uploaded data in bytes, so you can pass those return values to subsequent uses of ContinueUpload(Guid, Int64, Stream) and FinishUpload(Guid, Int64, Stream)

Namespace:  Microsoft.SharePoint.Client
Assembly:  Microsoft.SharePoint.Client (in Microsoft.SharePoint.Client.dll)

Syntax

'Declaration
Public Function StartUpload ( _
    uploadId As Guid, _
    stream As Stream _
) As ClientResult(Of Long)
'Usage
Dim instance As File
Dim uploadId As Guid
Dim stream As Stream
Dim returnValue As ClientResult(Of Long)

returnValue = instance.StartUpload(uploadId, _
    stream)
public ClientResult<long> StartUpload(
    Guid uploadId,
    Stream stream
)

Parameters

  • stream
    Type: System.IO.Stream

    The stream that contains the first fragment to upload.

Return value

Type: Microsoft.SharePoint.Client.ClientResult<Int64>
The size of the uploaded data in bytes.

Remarks

The following sample shows how overwrite an existing file by using the StartUpload, ContinueUpload, and FinishUpload methods.

        protected void UploadFile(object sender, EventArgs e)
        {
            var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
            using (var clientContext = spContext.CreateUserClientContextForSPHost())
            {
                //Get file from Shared Documents library and overwrite it.
                var documentsFolder = clientContext.Web.GetFolderByServerRelativeUrl("/Shared Documents");
                Microsoft.SharePoint.Client.File uploadFile = documentsFolder.Files.GetByUrl("file name");
                clientContext.Load(uploadFile);
                clientContext.ExecuteQuery();
                
                //Fetch new version of file from resources. Write the file contents to a stream.
                var inputFile = Properties.Resources.<resource file>;
                var inputStream = new MemoryStream();
                inputStream.Write(inputFile, 0, inputFile.Length);
                inputStream.Position = 0;

                //Set up size of fragments to upload.
                int chunkSize = 1000000;
                int index = 0;

                Int64 offset = 0;
                var myGuid = Guid.NewGuid();

                List<byte[]> chunkList = new List<byte[]>();

                while ( inputStream.Position < inputStream.Length)
                {
                    byte[] buffer = new byte[chunkSize];
                    int chunkBytesRead = 0;
                    while (chunkBytesRead < chunkSize)
                    {
                        int bytesRead = inputStream.Read(buffer, chunkBytesRead, chunkSize - chunkBytesRead);
                        MemoryStream stream = new MemoryStream();
                        stream.Write(buffer, 0, buffer.Length);
                        if (bytesRead == 0)
                        {
                            break;
                        }
                        chunkBytesRead += bytesRead;
                        if (index == 0)
                        {
                            offset = uploadFile.StartUpload(myGuid, stream).Value;
                            clientContext.ExecuteQuery();
                        }
                        else if (inputStream.Position == inputStream.Length)
                        {
                            uploadFile.FinishUpload(myGuid, offset, stream);
                            clientContext.ExecuteQuery();
                        }
                        else
                        {
                            offset = uploadFile.ContinueUpload(myGuid, offset, stream).Value;
                            clientContext.ExecuteQuery();

                        }
                    }

                    index++;
                }               

            }
            
        }

This method is currently available only on Office 365.

See also

Reference

File class

File members

Microsoft.SharePoint.Client namespace

Upload large files sample app for SharePoint