The SharePoint .NET client API provides a few methods which developers can use to upload files to a SharePoint server. Deciding on which one to use mostly depends on whether the file is larger than 2Mb, as SharePoint doesn’t allow you to upload files above that size using certain methods.
If you’re reading this blog, I’m assuming you’re interested in the sort of scenario that involves uploading existing files from a PC to a SharePoint site using a C# program. If you’re not interested in this kind of thing then you might be a bit bored, but I can’t stop you from reading so let’s get on with it.
Let’s take a look at the FileCreationInformation object – we can use this with an API call to specify a file to upload, and how to upload it. You can also set another flag to say whether you want the file to overwrite existing copies or not, which is something you might want to be careful setting. The properties we’re most interested in are the Content and ContentStream properties, as demonstrated here:
If you use the Content property to upload your file, it needs to be smaller than 2Mb in size or else SharePoint will refuse to let you upload it. That’s because you have to attach the entire contents of the file to the FileCreationInformation object as a byte array if you’re using that particular property.
On the other hand, you can also use the ContentStream property which accepts a FileStream instead of a pure array of bytes. Working with FileStreams can have a couple of advantages over byte arrays – in this scenario it allows the SharePoint API to stream the contents of the file to the server in a more manageable and reliable manner. With larger files, SharePoint is much more comfortable receiving the data in stream format and it’ll happily accept more hefty files (the upper limit is 50Mb by default but can be adjusted in the configuration).
I also lied two paragraphs ago; you can increase the maximum file size that SharePoint accepts while still using the Content property if you want, but there are reasons not to do so. The primary concern is that uploading larger files in a single message increases your odds of experiencing a timeout or other upload failure, but if you’re happy to take that risk then there are a couple of ways to tweak the settings.
Now that we know our limitations, let’s get a code snippet to conditionally upload a file using either a byte array or a FileStream, depending on the size of the file:
This code snippet will get your file into memory in whichever way is most appropriate. You might notice that I’m doing an “if (filesize > 1300000)” check, which is somewhat less than the 2Mb limit I mentioned earlier. This is because of the overhead that gets added to the message from its headers and extra information sent to SharePoint. So in reality you can try to upload a file that’s 2Mb in size using a byte array, but SharePoint will check the actual size of the whole message and probably ruin your plans. During my tests I found that roughly 1.3Mb was a safe value to use for this check, but you can feel free to fiddle around with higher values to see if you can squeeze some extra efficiency out of your uploads.
Once we’ve got our FileCreationInformation object nicely formed, we can send it off to SharePoint for processing:
You’ll notice that we nicely dispose of the FileStream if we used it earlier, so we don’t have open handles to system resources lying around when we shouldn’t. The ‘list’ and ‘context’ objects are required to perform any of this logic, but setting up a general SharePoint program has been covered a lot elsewhere so I won’t document the process of setting those up.
As an addendum, if you’re looking for a way to upload particularly large files using a batched process, you might want to check out the StartUpload method on the File class (in combination with ContinueUpload and FinishUpload). SharePoint supports using these methods to upload large files in chunks of data, allowing you to have finer control over the streaming process.
Thanks for reading, and happy SharePointing.