Upcoming changes to SharePoint and OneDrive for Business APIs to support # and % in file names

Enabling customers to seamlessly work with files and folders across end points is a key area of focus for the SharePoint team. To improve this, we’ve broadened the set of supported characters in OneDrive and SharePoint filenames and folders over time and are now working to support # and % characters. This, however, requires significant changes to our APIs that will impact partners that work with URLs and file names in SharePoint.

We are still finalizing our full API set to support this, but want to work with partners early to adapt to this change. Over the next several weeks we are working to start trials of a process to support # and % characters in file names across SharePoint Online and OneDrive for Business.  These trials will be opt-in by tenants, and we’ll evaluate how to roll out the feature more broadly over time. Please read the following to understand how these changes might affect your existing solutions.

Current File and Folder APIs

To  understand why this requires partners to evaluate many of their solutions, consider how we’ve been representing files in our APIs.  Behind the scenes, our APIs currently take in URLs as a String. Previously, there was no specific guidance around whether these URLs are decoded or percent-encoded, and SharePoint attempted to seamlessly handle all cases. Now that we are moving to support # and % characters, this seamless interpretation of URLs can cause ambiguity.

# character

Currently, when a developer passes URLs as a string with the # character in them, our API assumes that they mean a URL fragment as per RFC 3986, which is not significant to the file name. For example, in the current scenario when the developer calls:

Web.GetFileByServerRelativeUrl("/Shared Documents/Hello.txt#123")

we presume that name of the file is “/Shared Documents/Hello.txt” and we ignore the fragment “#123”. Once the # character becomes a supported character in file names, the file path becomes ambiguous; the implied file could be either “Hello.txt” or “Hello.txt#123”.

% character

The % character is used in encoded URLs to denote special characters, and currently, SharePoint uses that as a hint that the incoming URL has not been previously decoded.  Therefore, the following calls resolve to the same file within SharePoint: 

Web.GetFileByServerRelativeUrl("/Shared Documents/Hello%20World.txt")

  (where %20 is an encoded representation of a space.)

or

Web.GetFileByServerRelativeUrl(“/Shared Documents/Hello World.txt”) 

In the future, when a user wants to have both files ‘Hello%20World.txt’ and ‘Hello World.txt’ within a SharePoint document library, the above API cannot resolve both files discretely.

API Changes Moving Forward

To remove the ambiguity around intention, and to avoid breaking backwards compatibility with existing APIs, we are introducing a strongly typed, rich-featured representation of URLs to better represent the true developer intention of a URL.  

Specifically, we’ve introduced a new class (Microsoft.SharePoint.Client.ResourcePath).  This class can represent full (absolute) or parts (relative) of a URL for a site collection, site, file, folder or other artifact in SharePoint. It stores, expects, and returns the decoded format of the file path.  This class will be used to represent URLs across our APIs instead of string.  Throughout the object model, you will find ResourcePath used wherever we formerly took URLs, including Web.GetFileByServerRelativeUrl methods, File and Folder objects (which now have a .Path property), and APIs such as MoveTo.

Existing String-based URL APIs will still work as they have always, but because of backwards compatibility implications, they cannot be used with files with # and % in the name.  Existing solutions will generally work as they have always – at least, until users start to upload files with # and % in their names – and that is where issues may start.

Getting Started: Evaluate your code

Developers should evaluate their scenarios and use cases of files and folders in SharePoint.  They should also evaluate the lineage of URL paths in solutions – where can a user input a URL, and what is their intent and source in doing so?  Is it rejecting # and % in a way it may no longer need to?  When the developer gets a path from a different layer in the system – e.g., a browser API – is it already decoded, or should it be decoded?

Though the existing APIs will remain in place and function in the same manner for the forseeable future, your code may not have the expected semantic behavior when it encounters files in libraries with these new characters.  We strongly recommend that developers move to the new ResourcePath-based APIs.  Existing String-based file APIs will be marked as deprecated.

We’ll add more guidance and updates as we finalize this change – but wanted to provide an early look and to get developers started on evaluating this change.  Please provide your feedback via our TechCommunity. Thank you in advance to all of our partners as we go through this change.

FAQ

What is the timeline for this change?

Many of the ResourcePath based APIs are already available, and developers should start working with them.  We are putting in the finishing touches on the final complete API set, which you can expect to see in the next releases of SharePoint Online CSOM and Patterns and Practices CSOM APIs.  We will also put out more comprehensive guidance over the coming weeks as these APIs are completed.

We will work to create a per-tenant opt-in based mechanism so that customers can validate #/% support with their solutions.  We expect this mechanism will be available in some weeks from now. Beyond this initial opt-in trial, and based on customer feedback, we will further roll-out support; stay tuned for more announcements along these lines.

At what levels of the system is this support being added?

Files and folders will now be able to support # and % in their file name.

SharePoint list and document library can also have # and % in their URLs, but we do not plan to use # and % in list/library URLs created through the SharePoint user interface.

SharePoint sites (Web objects) and site collections (Site objects) can not have # and ; in their URL.

Will customers be notified when this change is implemented?

Yes, customers will receive notification as we roll out support for # and % characters in file names beyond an initial “opt-in” evaluation phase.

Will the old method of interacting with files remain supported?

Yes.  The existing API will continue to function consistently as they always have for all files without # or % in their URLs. When # and % support is enabled and a customer opts-in, it is important for you to validate your scenarios and ensure your scenarios are not impacted with the changed behavior.  

The existing API will NOT support files and folders with % and # in names.  For backwards compatibility reasons, files with URLs containing a # or % will be interpreted as either a URL fragment or an encoding hint, respectively.  With existing APIs, your code will not be able to save a file to SharePoint with a # or a % in them.

The existing API will be marked “Obsolete” in the future and will eventually be removed.

Does the new Path/ResourcePath API support files without # and %?
Yes.

Is SharePoint on-premises affected by this change?
There are no plans to introduce support of # and % characters to SharePoint on-premises releases.