Better SharePoint Framework Code with SPRemoteAPI 1.5 VSCode Extension

Technorati Tags: SharePoint Framework,VSCode,O365,Dev

I have been working with the new SharePoint Framework for the last month. This is the new Microsoft framework for SharePoint developers which makes it incredibly easily create web parts and web page applications using Typescript and other web technologies. I highly recommend switching to VSCode from Visual Studio when using this framework since it has greater flexibility for working with open source web technologies. The new framework relies heavily on the use of Typescript which gives you the ability to generate JavaScript code with compile time type checking along with intellisense to see available properties and methods while typing code.

SPRemoteAPI VSCode Extesnion

If you have ever worked with the SharePoint/O365 REST API you know that it is not easy to discover what types, methods and properties are available to you. When writing Typescript code you should always define your interfaces for REST responses and requests. The interfaces enable you to declare types which enables intellisense and type checking. Usually there are Typescript declaration files available for many framework libraries. The SharePoint REST API is not one of them. There are Typescript declarations for the SharePoint JavaScript Object Model but they are not kept up to date and do not match the REST API. It can be incredibly tedious to find REST example code and then go and create an interface for the request and response. Many developers will just create an interface and do some mapping from the REST response to a custom interface. This involves making the REST call and then examining the response to determine how to do the mapping.

SPRemoteAPI 1.5 Supports Creating Typescript Interfaces

Well I got tired of the error prone and laborious process of creating interfaces for the SharePoint REST API. I wanted something that would generate the interface for me that would automatically and exactly map to the response or request for a REST call. Many of the responses and request objects have properties that expose other complex types, so I wanted something that would create all the interfaces required to handle a response and request. So all you have to do is invoke the extension, then search for the type and click the “Create Interface” button.

After clicking the button all the interfaces that are exposed by the this type are created and put into the virtual declaration file. Since this file is virtual, you can then just copy whatever you want from this to your own declaration file. The “Create Interface” button is only visible on types that have properties. All properties are optional giving you the ability to choose which properties you use.

Once you have added this to a Typescript file and added an import statement you can now declare a type and get type checking along with intellisense for SharePoint REST response or request.

Get Productive with Intellisense and Type Checking

This feature will save you a lot of time having to research REST requests and responses. It will help you get up to speed on the SharePoint REST API and using the new SharePoint Framework. Enjoy.

Visual Studio Code Extension–SPRemoteAPI (SharePoint Office 365 REST API Discovery for the Masses)

Technorati Tags: VSCode,O365,SharePoint,Dev

For everyone who has ever used the Visual Studio extension SPRemoteAPIExplorer one of the pain points is the requirement that you had have SharePoint installed on the same box as Visual Studio. Now you can get the same basic functionality of being able to browse and discover what is available in SharePoint and Office 365 REST and JavaScript API without having to have SharePoint installed. You can type in a namespace and browse the methods and properties. You can determine if they are available to be used with REST and JavaScript. You can also see what is new in SharePoint 2016. Finally when looking at specific methods or functions the extension gives the required POST bodies and response payloads, allowing the developer to easily copy and paste this into his code. You can get the VSCode extension here SPRemoteAPI in the Visual Studio Market Place. Oh did I mention it is FREE.

Using SPRemoteAPI Extension (Step 1)

In VSCode just hit F1 and start typing SPRemoteAPI and you will see it appear in the drop down list.

 

Using SPRemoteAPI Extension (Step 2)

After selecting the SPRemoteAPI command you will be presented with all the available types in the SharePoint Office 365 remote API. You can start typing and the list will automatically filter as you type. The example below shows typing “move” and the list is filtered down to types with the word move contained in them. This list shows a github icon (flame) next to types that are new in SharePoint 2016. It also lists whether the type can be used in REST or JavaScript. Some types are not available for both.

Using SPRemoteAPI Extension (Step 3)

Once you selected the type you are presented a information dialog showing you the type along with options for displaying properties and methods. The options also shows you the number of each contained in the type.

Using SPRemoteAPI Extension (Step 4)

Select the methods options and you are presented a list of available methods to choose from.

Using SPRemoteAPI Extension (Step 5)

Choose a method and a new code window (virtual document) opened containing a JSON representation of all the method’s information needed to call it remotely using REST. It shows you the parameter types, required post body and response body. The post body can be copied into whatever REST calling framework you are using such as FETCH or JQuery. The response can be used to guide you in what to expect in the payload response from the call. This gives you ability to write remote REST calls without having to do all the extra experimentation to see what the call returns. Having both the body and response JSON templates will save you a lot of time searching on the internet.

What about properties?

Below is example of the code window you are given when you select properties. It shows you all the available properties for the type and the information you need to determine what is available remotely from SharePoint Office 365.

SPRemoteAPI in Action

 

SPRemoteAPI VSCode Extension – SharePoint Office 365 REST Discovery at your fingertips

This Visual Studio Code extension was created to open up the SharePoint Office 365 remote API to the many developers who do not use Visual Studio to develop. This extension will run on non-windows environments and of course does not require SharePoint to be installed locally. You can now easily figure out what is available and how to call any SharePoint REST API without having to search and page through mounds of documentation. Enjoy being productive!

Understanding SharePoint 2016 Remote API Changes (SPRemoteAPIExplorer 3.0)

Technorati Tags: SP2016,SP2013,Dev,Apps

Well SharePoint 2016 has been released and you have no clue what new features are available from the remote API. There are a total 250 new types you can use and changes to an existing 86 types. This results in thousands of new properties and methods that are undocumented. You can now get started on understanding the changes with the updated SPRemoteAPIExplorer 3.0 Visual Studio extension. I have used this extension for years to find and discover new methods to call in the SharePoint 2013 remote API. If you have used it before you will know it can generate the Ajax REST method calls for you, create JSON for REST responses and payloads or create JSON object paths for deeply nested responses. Version 3.0 now gives you the ability to switch between SharePoint 2013 and SharePoint 2016 remote API’s. It also surfaces the complex types that are used as parameters and responses, this will give you a better understanding of the wide range of types that you need to know to code effectively against SharePoint On-Premises or Online. Finally, it gives you an option to see just the types that are new or have changed, which will make it easy to see and discover some of the great things that may make your coding life easier. Remember that the SharePoint 2016 remote API applies to both On-Premises and Online, but some methods may work only in SharePoint Online.

Easily Identify Remote API changes in SharePoint 2016

To easily find the new changes right click the top node to see the main context menu and select the “View only new and changed” menu item.

After clicking this menu item the explorer tree only shows types that are new or types that have changes. All new and changed features are identified with a “red dot” in their icons.

Show Complex Types used in the Remote API

Clicking the “Show complex types” menu item will load all the complex types into the explorer. Typically these types are used as parameters and responses and contain no methods.

Discover if Methods are supported by REST

Remember that you can click on a method or any node and discover it’s capabilities. If you click on a method and view its properties you can see if the method is supported for REST, CSOM or JSOM.

Generate Ajax code for Methods

If you select the “Create $ajax call” context menu item for a method it will copy all the code including the JSON payload for the REST call into the clipboard. You can then copy and paste this into your code. You can also generate the JSON and response paths for method responses.

Visions for Visual Studio Code

There have been past complaints that this extension is dependent upon SharePoint being installed locally. SPRemoteAPIExplorer 3.0 is dependent only upon Visual Studio Office Tools, but the extension relies on the “SharePoint Server Explorer” tool to surface the API nodes. Unfortunately, this explorer will only work with SharePoint being installed. So I am currently working on a VS Code extension to surface this information. Unfortunately, it will not be as full featured as this extension but it will allow other developers to access this information. Another option would be to expose this information as a service.

Time to Catch Up on your API

SharePoint 2016 is released so you better start catching up. I hope this new extension will help you do that and become more productive. I plan on keeping this up to date as API changes are pushed to On-Premises. It would be nice to be able to get this information from O365 instead of waiting for the On-Premises push. Enjoy.

What’s new in SharePoint 2016 Remote API Part 4 (Web)

Technorati Tags: SP2016,O365,ECM

This is my fourth post about the new SharePoint 2016 remote API. This new post will cover the 18 new methods and 8 new properties in the Microsoft.SharePoint.SPWeb class. I am now working with the SharePoint 2016 RC released on January 20th. It is evident that there will be exposed methods on the Remote API which will be callable but throw a not implemented error in SharePoint On-Prem.

New SPWeb Methods

CreateAnonymousLink

This method is callable from REST or JavaScript. It takes a URL to a document and a boolean to give access to edit the document. It will return a string representing a anonymous URL that will not expire. It is not implemented in On-Prem. It is implemented in SharePoint Online but from my testing it will only work from a personal site. You cannot use it from an Add-In hosted outside of a personal site. You will receive a “MountPoint” security error. “MountPoint” is another word for OneDrive.

CreateAnonymousLinkWithExpiration

This method is callable from REST or JavaScript. It takes a URL to a document and a boolean to give access to edit the document, and a string representing an expiration date. It will return a string representing a anonymous URL that will expire on the date given. The valid formats for the date string are "yyyy-MM-ddTHH:mm:ssK", "yyyyMMddTHHmmssK". This method is not implemented in On-Prem. It is implemented in SharePoint Online but from my testing it will only work from a personal site. You cannot use it from an Add-In hosted outside of a personal site. You will receive a “MountPoint” security error.

CreateOrganizationSharingLink

This method is callable from REST or JavaScript. It takes a URL to a document and a boolean to give access to edit the document. It will return a string representing a URL that everyone in the organization can access that will not expire. It is not implemented in On-Prem. It is implemented in SharePoint Online but from my testing it will only work from a personal site. You cannot use it from an Add-In hosted outside of a personal site. You will receive a “MountPoint” security error.

DefaultDocumentLibrary

This method is usable from JavaScript and REST and will return the “MySite” document library if the SPWeb is a personal site, otherwise it returns the document library identified in a SharePoint resource file with the key of  “documents_folder”, which is typically “Shared Documents”.

DeleteAllAnonymousLinksForObject

This method does what it exactly says. Given a URL it will remove all sharing permissions for anonymous links created by the previous listed methods. This is callable from both REST and JavaScript. Caller must have manage permissions privileges.

DeleteAnonymousLinksForObject

This method does exactly what DeleteAllAonymousLinksForObject does. Very difficult to tell the difference between the two. This is callable from both REST and JavaScript. Caller must have manage permissions privileges. This is not implemented in SharePoint On-Prem.

DestroyOrganizationSharingLink

This destroys a previously issued organization wide shared link using the CreateOrganizationSharingLink method using the URL passed in. Once again this method is not available on SharePoint On-Prem.

ForwardObjectLink

This method which is usable from JavaScript and REST will create and forward a view only email link to multiple users. The parameters are the URL of the document you want to share, the string representation of output from the people picker, an email subject and body. This is not available on SharePoint On-Prem. This method will throw an error if any of the people selected are external or do not have view rights to the document.

GetContextWebThemeData

This is a static method which is only available through REST. This will return a JSON representation of the new beefed up SPTheme class. The method will call and get the current web’s theme information and render all the theme information you would ever need to help you match the current theme. Below is screen shot of the result after calling JSON.parse on the return string. As you can see it returns colors, background image, fonts and much more. You will need to look more closely at Microsoft.SharePoint.Utilities.SPTheme to understand what is returned.

GetDocumentLibraries

This is very nice method to return a collection of SPDocumentLibraryInformation objects for the given URL passed as an argument. This is effecient since it is a static method, making it easy to build lists of document libraries in a given web. Below is screen shot of the return data. It has a property telling you the last date the title of the document libary was changed.

GetFileByGuestUrl and GetFileByLinkingUrl

Both these methods are a great way to access a file given links generated by the CreateLinkxxx methods on the SPWeb class. The GetFileByGuestUrl will validate the URL checking for the guest access token and whether it is expired. The GetFileByLinkingUrl checks for a unique id in the querystring and returns the file using that. Both are available for JavaScript and REST.

GetFileById and GetFolderById

Both these methods use the unique id (GUID) of the file or folder to return the file. Developers have been asking for this for a while. But also probably put in for OneDrive.

GetObjectSharingSettings

This static method will return a Microsoft.SharePoint.ObjectSharingSettings object. This object contains many properties that tells you what sharing capabilities the current user has for the document URL passed as an argument. For example, can the user share the document with an external user or can the current user edit the document.It also takes a group id and a boolean to use simplified roles. Not sure what these may be used for. This method is not implemented in SharePoint On-Prem and can only be used on a personal MySite in SharePoint Online. The method seems to be a great way to determine all the different permissions a user has for a document. Unfortunately, it is limited in its implementation.

IncrementSiteClientTag

This method availalble for REST and JavaScript will increment a tag value that is possibly used to flush the cached web controls for pages in a given site.

ShareObject

Static method to share an object such as a document and very similar to the ForwardObjectLink method. This method has more parameters such as the ability to propagate which settting this to true appears to solve some past problems with pushing permissions down to nested AD groups and universal security groups. This method also gives you an option to send an email or just give permissions to the object.

UnShareObject

Static method doing the opposite of the ShareObject method, both ShareObject and UnShareObject return a Microsoft.SharePoint.SharingResult.

New SPWeb Properties

ContainsConfidentialInfo

This property returns true or false if the site contains any confidential information determined by the in place data loss protection policy. Typically this property is used when a DLP policy is implemented through the Compliance center.

CurrentChangeToken

Used by web part pages hosted in the site to determine if the site has changed.

DataLeakagePreventionStatusInfo

This property returns a Microsoft.SharePoint.SPDataLeakagePreventionStatusInfo class for the site and tells you whether the site contains confidential information and if external sharing DLP tips are enabled. This class also gives two help information URL’s for both. You can read more about DLP and SharePoint 2016 here.

MembersCanShare

True or false if sharing has been enabled on the site.

RequestAccessEmail

If the site has the email service configured and is not hosted on a virtual server, then this property will return the email address to request access to the site.

ThemeData

Property which exposes the same JSON as the GetContextWebThemeData method.

ThirdPartyMdmEnabled

This property will return true if the site is using a third party mobile device management solution.

TitleResource

Returns a Microsoft.SharePoint.SPUserResource containing the title of the site. Apparently useful for publishing.

SharePoint 2016 is all About Sharing, Security and OneDrive

As you can see that many of the methods and properties are devoted to sharing and data loss prevention. This seems to be the theme in the new features for SharePoint 2016. As a developer you must be aware the remote API code bases for SharePoint On-Prem and SharePoint Online have been merged. Many of the methods are not implemented at this time in On-Prem. It is very difficult to determine this unless you experiment. It appears that some of these methods can be enabled at a later time using flighting (enabling features using code). More to come.

What’s new in SharePoint 2016 Remote API Part 3 (Files)

Technorati Tags: ECM,SP2016

This is part three of a blog series about the new features available in SharePoint 2016 Beta 2 Remote API. This blog post will talk about the new features for files. Unfortunately, some of the new methods available for files do not necessarily work in Beta 2 for reasons I don’t understand as of yet.

File Versions

Getting previous version binaries in SharePoint has always been a pain. CSOM methods really did not work. Many developers used File.OpenBinaryDirect method along with the URL to the previous version which looked something like this: http://yoursite/yoursubsite/_vti_history/512/Documents/Book1.xls

Of course you knew that 512 means version 1.0 or the magic number 1025 means version 2.1. There was a fomula that you were required to use to generate these numbers and construct the URL. However, even if you knew how to constuct the URL the CSOM OpenBinaryDirect method would return a 404. Most developers just used the .Net web client and the URL to get the binary. Now SharePoint 2016 has added OpenBinaryStream method on the SPFileVersion class.

The OpenBinaryStream method is available for both CSOM, REST and JSOM. The following is a code example using JSOM. Unfortunately, this still has the problem of decoding the binary stream similar to the issue of getting the binary for a SPFile object pointed out in Mikael Svenson blog post How to copy files between sites. If the file is not a text file then you get a file that has all the pages but the pages are blank. This problem still exists in SharePoint 2016. So I recommend using this method only with managed CSOM. Also, you still need to know the magic number for the version to retrieve it. The SPFileVersions collection has many methods that use the label, except the method to retrieive it. I can delete by the label but not retrieve by the label. Why?

function getVersionBinarySP() {
    var dfd = $.Deferred();
    var binaryData;
    hostweburl = decodeURIComponent(getQueryStringParameter('SPHostUrl'));
    appweburl = decodeURIComponent(getQueryStringParameter('SPAppWebUrl'));
    fileContentUrl = appweburl + "/_api/SP.AppContextSite(@target)/web/GetFileByServerRelativeUrl('/sites/seconddev/testdups/testdoc0.pdf')/Versions/GetById(512)/OpenBinaryStream?@target='" + hostweburl + "'";

    var executor = new SP.RequestExecutor(appweburl);
    var info = {
        url: fileContentUrl,
        method: "GET",
        binaryStringResponseBody: true,
        success: function (data) {
            binaryData = data.body;
            dfd.resolve(binaryData);
        },
        error: function (err) {
            dfd.reject(err);
        }
    };
    executor.executeAsync(info);
    return dfd;
}

What’s new for Files?

There a many new methods and properties available for remotely accessing SharePoint files. Some of these have already been implemented in SharePoint Online. Below is a list of the new methods.

StartUpload, ContinueUpload, ContinueUpload, FinishUpload Methods

These methods are for uploading files in fragments (chunking) which is useful for large files when connections can be dropped or throttled. SharePoint Online has had these methods for a while to help developers with throttling. The methods are enabled for CSOM, REST and JSOM. Once again I would not try using these from JavaScript given the issues with stream encoding. I did test these with managed CSOM, below is some code:

public void UploadFile()
{
    ClientContext clientContext = new ClientContext("http://win2012r2dev/sites/seconddev");

    var documentsFolder = clientContext.Web.GetFolderByServerRelativeUrl("/sites/seconddev/testdups");
    Microsoft.SharePoint.Client.File uploadFile = documentsFolder.Files.GetByUrl("testdoc12.pdf");
           
    clientContext.Load(uploadFile);
    clientContext.ExecuteQuery();

    using (var fs = System.IO.File.OpenRead(@"c:\wp8_enterprise_device_management_protocol.pdf"))
    {
        byte[] bytes = new byte[fs.Length];
        fs.Read(bytes, 0, (int)fs.Length);
        using (var inputStream = new MemoryStream())
        {
            inputStream.Write(bytes, 0, bytes.Length);
            inputStream.Position = 0;

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

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

            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++;
            }

        }
    }

}

These methods all work together to help upload files in fragments. You just need to make sure to use the same GUID when sending the request. Unfortunately, I could not get this to work. I keep getting a Cobalt (File Syncronization) error of “Invalid Argument”. However, please try the code I could be missing something.

ExecuteCobaltRequest Method

Once again this is a method for editing files that are supported by the Office Online Server (WOPI Protocol) that has been available in Office 365. This method is now supported for SharePoint 2016 and Office Online Server Preview. There is little documentation on this method, The method is supported in managed CSOM and JSOM. The method takes a stream as an argument so probably not a good candidate for JavaScript.

GetImagePreviewUrl

This method returns a URL to the new image preview handler that has been used by Delve in Office 365. I blogged about using this in your own hosted Add-In or search templates Get Faster Search Previews in SharePoint Online. Well now a handy method will build if for you in SharePoint 2016. This will work with office, pdf, tiff, bmp and png files. You can pass in the width and height and it will calculate a resolution and send back a URL similar to this:

http://win2012r2dev/sites/SecondDev/_layouts/15/getpreview.ashx?path=/sites/SecondDev/testdups/testdoc0.pdf&resolution=Width300&clienttype=webapp 

Unfortunately, the getpreview.ashx handler code will not work unless it is running on SharePoint Online. Huh?

GetPreAuthorizedAccessUrl

This method returns a URL to download the document. The method takes an integer as an argument representing the number of hours the link is good for. It has a guest token attached in the querystring. Below is an example of what is returned. You will have to log in with the userid listed in the querystring.

http://win2012r2dev/sites/SecondDev/_layouts/15/download.aspx?guestaccesstoken=NduByOVhPo1QJyW0FEZVaikciOnDC03opCSiUWylH4s%3d&docid=0bfef46a04c964c7e983248c2051709fa&expiration=12%2f31%2f2015+6%3a11%3a57+AM&userid=1&authurl=True

GetWOPIFrameUrl

This is another convenience method. This is a URL to navigate to an office file (including PDF) in Office Online Server Preview. The method takes one argument an integer representing the SPWOPIFrameAction enumeration. This method supports, View, Edit, InteractivePreview, and MobileView. Below is an example of what is returned.

http://win2012r2dev/sites/SecondDev/_layouts/15/WopiFrame.aspx?sourcedoc={bec083e0-6ba6-4b87-9937-5f3c488e2f8a}&action=interactivepreview

Update

The SPFile and SPFolder now support property bags via the remote API. So you can now save metadata to your file and folders using the new Properties property along with this Update method.

function updateFilePropertyBag() {
    appweburl = decodeURIComponent(getQueryStringParameter('SPAppWebUrl'));
    hostweburl = decodeURIComponent(getQueryStringParameter('SPHostUrl'));
    context = new SP.ClientContext(appweburl);
    appContextSite = new SP.AppContextSite(context, hostweburl);

    targetWeb = appContextSite.get_web();
    var file = targetWeb.getFileByServerRelativeUrl("/sites/seconddev/testdups/testdoc0.pdf")
    var properties = file.get_properties();
    
    context.load(file);
    context.load(properties);

    context.executeQueryAsync(function () {
        var p = properties;
        p.set_item("whatever", false);
        file.update();

        context.executeQueryAsync(function () { },
            function (sender, args) {
                alert(args.get_message() + '\n' + args.get_stackTrace());
        });

    }, function (sender, args) {
        alert(args.get_message() + '\n' + args.get_stackTrace());
    });

}

Information Rights Management is a high priority in SharePoint 2016

Below is a list of new properties exposed on the SPFile in th remote API. As you can see Information Rights Management is a high priority with the surfacing of two new properties InformationRightsManagementSettings and EffectiveInformationRightsManagement. The former is the default settings and the later is what actually is set for the document if IRM is enabled. These settings are stored in the SPFile property bag but these new properties make it easy to read the right property. This comes in handy if your developing an application and you want to make sure you can print or view a document.

SharePoint 2016 Remote API Progress but not Perfection

Well this post shows you that the remote API for files is getting better in SharePoint 2016, but problems remain. The current Beta 2 remote API seems to be ahead of the what has been implemented on the server side. Some features appear in the API but are not fully implemented or may never be implemented. If some of the methods are for O365 only then they should be removed. The merging of the API between O365 and SharePoint 2016 may cause problems for developers since it will be impossible to tell which method works in what platform. There is more information to come. I urge you to start using the remote API more so you can take advantage of new features when your customers need them and to avoid the ones that do not work.