Skip to content

Release Notes RC0

Jump to bottom
Vesa Juvonen edited this page Jan 23, 2017 · 5 revisions

RC0

Here is the RC0 drop. As far as we are aware, this is pretty much what the final release will look like. The classes are in the final packages, the APIs are in the right classes, the serialization model is fleshed out, etc. As far as we know, there should not be breaking changes from now on. However, there are a few things that cropped up at the last minute that will need to be fixed before we hit GA (General Availability)

  • The internal and alpha APIs are still showing up. The intellisense should show that they are internal/alpha. Don't use them. They will be removed soon.
  • There are a few issues with classic pages. First - the serialization format is going to change, so webparts you configure today will probably break. Note that your webpart code won't need to change, only that you will need to delete the webpart and recreate it. Additionally, we are removing the need to have a webpart file in the package. The Yeoman generator is currently still adding the webpart to the app package. This will be removed shortly.

Should you get the new bits yet?

We're doing this drop a bit differently. In the past we've gone out of our way to make sure that webparts work from one build to the next, and because of this, we've generally waited until all of the service was updated before releasing the code on NPM / making an announcement. However we've had to make some breaking changes this time due to the scope of the changes. The updates should start rolling across the service starting January 9th, and should be finished by the end of that week. Here's what you can do to get started.

  • You can grab the latest code from npm right away and build and test locally.
  • You can also take a look at the workbench in your service (now conveniently located at sites/_layouts/15/workbench.aspx). If you open the debugger, the files being served from spoprod-a.akamaihd.net should be files/sp-client-prod_2017-01-02.015 or later. (basically, make sure it looks like 2017*, not 2016*). We'll make it easier to see this in the future, but that's how to tell for sure at the moment.
  • If your webpart starts failing, you've probably been upgraded. Grab the RC0 release and start coding.

We're working on getting all of the documentation updated and rolled out. This may lag a bit. If you see references to sp-module-loader or sp-client-preview, chances are that update is pending and should be released soon. If you are seeing references to sp-loader, sp-webpart-base and sp-http, that content has been upgraded. If you see anything strange or have any questions that can't be answered in 140 characters, log an issue in the issues list on this github.

Getting the new bits

Make sure that your @microsoft/generator-sharepoint npm package is version 0.4.1. To get the latest version, run npm i -g @microsoft/generator-sharepoint@latest

Updating your existing projects

To be honest - it's probably easiest to create a new project at this point, but if you want to upgrade an existing one, this is what you should do.

Update your package.json file

Open package.json and set the versions of the following packages in the "dependencies" section. A couple of things to note - you should no longer be referencing sp-client-preview, and there is a new @types/webpack-env package.

  • "@microsoft/sp-client-base": "~0.7.0",

  • "@microsoft/sp-core-library": "~0.1.2",

  • "@microsoft/sp-webpart-base": "~0.4.0",

  • "@types/webpack-env": ">=1.12.1 <1.14.0"

Update your "devDependencies" section. Note the two new @types package references

  • "@microsoft/sp-build-web": "~0.9.0",

  • "@microsoft/sp-module-interfaces": "~0.7.0",

  • "@microsoft/sp-webpart-workbench": "~0.8.0",

  • "gulp": "~3.9.1",

  • "@types/chai": ">=3.4.34 <3.6.0",

  • "@types/mocha": ">=2.2.33 <2.6.0"

Update your "scripts" section

  • "clean": "gulp clean",

Update config.json

You should no longer need the default entries in the externals section. You can remove:

  • "@microsoft/sp-client-base": "node_modules/@microsoft/sp-client-base/dist/sp-client-base.js",

  • "@microsoft/sp-webpart-base": "node_modules/@microsoft/sp-webpart-base/dist/sp-webpart-base.js",

  • "@microsoft/sp-client-preview": "node_modules/@microsoft/sp-client-preview/dist/sp-client-preview.js",

  • "@microsoft/sp-lodash-subset": "node_modules/@microsoft/sp-lodash-subset/dist/sp-lodash-subset.js",

  • "office-ui-fabric-react": "node_modules/office-ui-fabric-react/dist/office-ui-fabric-react.js",

  • "react": "node_modules/react/dist/react.min.js",

  • "react-dom": "node_modules/react-dom/dist/react-dom.min.js",

  • "react-dom/server": "node_modules/react-dom/dist/react-dom-server.min.js"

Update your webpart.manifest.json file

We've changed the way we handle the some property types. Most people weren't using this, but in case you were:

  • note down your entries for "searchablePropertyNames", and delete them from the manifest.

  • note down your entries for "imageLinkPropertyNames" and delete them from the manifest.

  • Follow the instructions towards the end of this document called "ServerProcessedData"

Update your tsconfig.json file

  • after the sourcemap entry, add "types": [ "webpack-env" ]
  • don't forget that you'll need a , on the preceeding line.

Update node_modules

  • delete your node_modules folder and run npm i

  • This will update all the packages then optimize the node_modules folder size.

update your *.tests.ts file

  • On the first line, insert /// <reference types="mocha" />
  • update the assert import to be import { assert } from 'chai';

update your webpart code

  • 'protected get propertyPaneSettings(): IPropertyPaneSettings' should now be 'protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration '

  • Take a look at the updated page context variable (this.context). Some functionality you may have been using has been moved around. Things like updating the refreshing pane have shifted a bit.

  • The move to @types might make things a bit tricky with duplicate typings showing up. You'll want to remove the older typings that were added via tsd and them via npm i @types/typenamehere --save

  • The HttpContext has changed a bit, moving packages (@microsoft/sp-http) and names (now SPHttpContext). We've also introduced the notion of configurations, so you'll need to pass one of those in. The lab that connects to SharePoint should be updated to show to do this, but in case the update hasn't made it to the site yet, do something the following:

    import {SPHttpClient, SPHttpClientConfigurations} from '@microsoft/sp-http';

    return this.context.spHttpClient.get(this.context.pageContext.web.absoluteUrl + '/_api/web/lists?$filter=Hidden eq false', SPHttpClient.configurations.v1)

rebuild

  • Run gulp clean to clean up any old build artifacts

  • Run gulp to build your updated project

What changed in this drop?

Quite a few changes in this drop.
We've migrated from typings to @types for the typescript typings, and introduced decorators to help describe our interfaces to support things like virtual, sealed and override We've renamed the .spapp extension to .sppkg when you build your package

sp-client-base package

  • removed a large number of internal interfaces
  • removed HttpClient and all its related classes. (sp-http has updated versions)
  • removed the Compare class
  • removed CultureInfo class (sp-page-context has an updated version)
  • removed IOData* classes (sp-odata-types has updated versions)
  • removed SP* classes (sp-page-context has updated versions)
  • removed PageContext (sp-page-context has an updated version)

sp-client-preview package

You should really no longer need this package for most work, as we've pulled all the relevant classes into proper packages

  • removed BaseClientSideWebPart (sp-webpart-base has the updated version)
  • removed Canvas (we'll bring it back when we roll out other customizations)
  • removed IHTMLProperties (we've rev'd how these work, and the new implementation is in sp-webpart-base)
  • removed all the IOData* classes (sp-odata-types has the updated versions)
  • removed all the IPropertyPane related classes (sp-webpart-base has these now)
  • removed IWebPartContext (sp-webpart-base has this)
  • removed IWebPartData (this has been updated with the IHtmlProperties class. Updated version is in sp-webpart-base)

sp-core-library package

This is a new package that contains library functions that enable the framework's core functionality

  • Added DisplayMode (edit, display)
  • Added EnvironmentType (Information about the current environment the code is running in)
  • Added Guid
  • Added (I)RandomNumberGenerator
  • Added IServiceCollection (moved)
  • Added (I)TimeProvider (moved)
  • Added Log (moved)
  • Added ServiceKey (moved)
  • Added ServiceScope (moved)
  • Added UrlQueryParameterCollection (helper to do some query string manipulation)
  • Added UrlUtilities (helper to do some URL manipulating)
  • Added Validate (class to do simple argument validation)
  • Added Version (class to do simple semver logic)

sp-http package

This is a new package that contains all of the Http* classes that existed in other packages previously. We expect other subclasses in the future to make it easy to connect to other O365 services.

  • Renamed HttpClient to SPHttpClient
  • Renamed BasicHttpClient to HttpClient
  • Added (I)HttpClientConfiguration to make it easy to organize Http configuration settings (like headers, odata versions, etc.)
  • Added HttpClientResponse (This is essentially an extension of the standard Response class to handle some SP scenarios)
  • Added SPHttpClientConfigurations which contains some specific common configurations

sp-loader package

This is a rename of the sp-module-loader package.

  • Added SPComponentLoader (used for loading css, script and client side components)

sp-module-interfaces package

This contains most of the manifest definition code

  • Added IClientSideComponentManifest (main interface for defining all client side component manifests)
  • Added IClientSideLibraryManifest (defines the library component manifest)
  • Added IClientSideWebPartManifest (defines the webpart component manifest)
  • Added IClientSideWebPartManifestEntry (defines the preconfigured entries in the webpart manifest)
  • Added ILocalizedString (defines how localized strings are represented in a manifest)

sp-odata-types package

  • Marked IODataUser as public

sp-page-context package

This package (and its classes) now contain the majority of the information that was previously in the spPageContextInfo object. the spPageContextInfo window variable will be going away. You should interact with the page context object to get the relevant information.

  • Added SPPermission class

SpListItem class

  • Added permissions property

SpSite class

  • Marked as public
  • Added cdnPrefix: string
  • Added classification: string
  • Added correlationId: Guid
  • Added isNoScriptEnabled: boolean
  • Added recycleBinItemCount: number
  • Added serverRequestPath: string
  • Added sitePagesEnabled: boolean

SPUser class

  • Marked as public
  • Added isAnonymousGuestUser: boolean
  • Added isExternalGuestUser: boolean

SPWeb class

  • Marked as public
  • Added isAppWeb: boolean

sp-webpart-base package

  • Marked IClientSideWebPartStatusRenderer as public
  • Renamed (and expanded) IHtmlProperties to be ISerializedServerProcessedData
  • Created ISerializedWebPartData
  • Marked IPlaceholderProps as public
  • Marked IPlaceholderSpinnerProps as public
  • Marked IPropertyPaneButtonProps as public
  • Marked IPropertyPaneChoiceGroupProps as public
  • Renamed IPropertyPaneSettings to IPropertyPaneConfiguration
  • Marked IPropertyPaneGroup as public
  • Marked IPropertyPaneLabelProps as public
  • Marked IPropertyPanePage as public
  • Marked IPropertyPanePageHeader as public
  • Marked IPropertyPaneSliderProps as public
  • Marked IPropertyPaneToggleProps as public

IWebPartContext

  • Removed environment: LegacyEnvironment
  • Moved isPropertyPaneRenderedByWebPart, openPropertyPane, refreshPropertyPane to IPropertyPaneAccessor
  • Renamed HttpClient and BasicHttpClient to spHttpClient and HttpClient

IWebPartData

  • Marked as public
  • Now extends ISerializedWebPartData
  • Removed htmlProperties

IPropertyPaneTextFieldProps

  • Marked as public
  • Added disabled?: boolean

IPropertyPaneLinkProps

  • Marked as public
  • Added disabled?: boolea

IPropertyPaneCustomFieldProps

  • Marked as public
  • Added key: string

IPropertyPaneDropdownOption

  • Marked as public
  • Removed isSelected

IPropertyPaneDropdownProps

  • Marked as public
  • Renamed isDisabled? to disabled?

IPropertyPaneField

  • Marked as public
  • Added shouldFocus?: boolean

IPropertyPaneCheckboxProps, IPropertyPaneChoiceGroupOption

  • Marked as public
  • Renamed isChecked? to checked?
  • Renamed isEnabled? to disabled?

BaseClientSideWebPart

  • Added accessibleTitle: string
  • Added dataVersion: Version
  • Removed deserialize
  • Removed dispose
  • Added getPropertyPaneConfiguration(): IPropertyPaneConfiguration
  • Changed onBeforeSerialize() to not have a return type and marked it as virtual
  • Added onAfterDeserialize(deserializedObject: any, dataVersion: Version): TProperties
  • Marked onAfterPropertyPaneChangesApplied() as virtual
  • Marked onDisplayModeChanged(oldDisplayMode: DisplayMode) as virtual
  • Marked onDispose() as virtual
  • Marked onInit() as virtual
  • Marked onPropertyPaneConfigurationComplete() as virtual
  • Marked onPropertyPaneConfigurationStart() as virtual
  • Marked onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any) as virtual
  • Marked onPropertyPaneRendered() as virtual
  • Removed openPropertyPane (still on context object)
  • Removed propertyPaneRenderedByWebPart (still on context object)
  • Removed refreshPropertyPane (still on context object)
  • Renamed propertyPaneSettings to be propertiesMetadata
  • Marked render() as abstract

IClientSideWebPartStatusRenderer

  • Marked as public

Yeoman Generator

  • Fixed up to work with all the new APIs / packages
  • In the framework agnostic starting code, we safely encode non-html properties like description.

ServerProcessedData

We've changed how the value-added properties are handled. In the past, you would add entries to your manifest.json file and state what properties should have link fixup, which were images, and which should be treated with the traditional HTML field content logic, which strips out unsafe content (like script tags) and gets entered into the search index. This has changed a bit. You now override the propertiesMetadata base method.

protected get propertiesMetadata(): IWebPartPropertiesMetadata {
  return {
    'imageSource': {isImageSource: true},
    'captionText': {isHtmlString: true},
    'targetUrl': {isLink: true}
  };
}

Note that you will need to import IWebPartPropertiesMetadata from sp-webpart-base

What's coming up?

Fixes to how we serialize webpart data on classic pages. This won't be a change to any client code, but rather the code running in the service. As such, you won't need to make any changes, just be aware that some webparts created on classic pages may cease to work in the future. You'll need to delete them and re-add them to the page.

Submit an issue || Discuss at SharePoint StackExchange || Submit your new idea at Uservoice

Clone this wiki locally