Skip to content

Commit 262796d

Browse files
waldekmastykarzVesaJuvonen
waldekmastykarz
authored and
VesaJuvonen
committed
Added guidance on debugging on modern pages (SharePoint#1609)
1 parent f22162d commit 262796d

File tree

3 files changed

+191
-0
lines changed

3 files changed

+191
-0
lines changed

‎docs/images/debug-sharepoint-toolbox-modern-page-local-webpart.png

245 KB
Loading

‎docs/spfx/debug-modern-pages.md

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
title: Debug SharePoint Framework solutions on modern SharePoint pages
3+
description: Guidance on how to debug SharePoint Framework solutions on modern SharePoint pages
4+
ms.date: 04/06/2018
5+
ms.prod: sharepoint
6+
---
7+
8+
# Debug SharePoint Framework solutions on modern SharePoint pages
9+
10+
When building SharePoint Framework solutions, you can test them on modern SharePoint pages. For building SharePoint Framework extensions, testing on modern pages is the only option, since at this moment the SharePoint Workbench doesn't support loading extensions. Testing on modern pages can however be also used for debugging web parts where it offers developers additional value.
11+
12+
> [!IMPORTANT]
13+
> While there are no technical restrictions for debugging local SharePoint Framework solutions on modern SharePoint pages, you should be careful when using it in your production tenant. This capability allows you to execute code that hasn't been tested and verified against your organization's policies and could be harmful to your production data.
14+
15+
## Debug SharePoint Framework extensions on modern SharePoint pages
16+
17+
At this moment, SharePoint Framework extension can be debugged only on modern SharePoint pages. SharePoint Workbench doesn't support testing extensions. Depending on the version of the SharePoint Framework that you use, there are different ways to debug extensions on modern pages.
18+
19+
### Debug extensions using serve configuration
20+
21+
Starting from version 1.3.0, when you add a SharePoint Framework extension to your project, the SharePoint Framework Yeoman generator will extend your project's configuration. Using this configuration, you can automatically start a modern SharePoint page in your web browser with all parameters required to debug the extension on that page already present.
22+
23+
#### How it works
24+
25+
When you add a new SharePoint Framework extension to your project, the SharePoint Framework Yeoman generator will add a new entry to the `config/serve.json` file in your project. A sample entry looks as follows:
26+
27+
```json
28+
{
29+
"$schema": "https://dev.office.com/json-schemas/core-build/serve.schema.json",
30+
"port": 4321,
31+
"https": true,
32+
"serveConfigurations": {
33+
"default": {
34+
"pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
35+
"customActions": {
36+
"d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
37+
"___location": "ClientSideExtension.ApplicationCustomizer",
38+
"properties": {
39+
"testMessage": "Test message"
40+
}
41+
}
42+
}
43+
},
44+
"helloWorld": {
45+
"pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
46+
"customActions": {
47+
"d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
48+
"___location": "ClientSideExtension.ApplicationCustomizer",
49+
"properties": {
50+
"testMessage": "Test message"
51+
}
52+
}
53+
}
54+
}
55+
}
56+
}
57+
```
58+
59+
Next to the default configuration, the SharePoint Framework Yeoman generator will create an entry for each extension that you add to your project. Each entry contains a URL of the modern page that should be used to test the particular extension, the list of extensions that should be loaded and for each extension, the list of properties that should be set on them. To use the particular serve configuration, execute in the command line:
60+
61+
```sh
62+
gulp serve --config=<name>
63+
```
64+
65+
for example:
66+
67+
```sh
68+
gulp serve --config=helloWorld
69+
```
70+
71+
After running this command, gulp will start your web browser with the modern page specified in your configuration. The page will show a popup asking you to confirm that you now will be loading debug scripts.
72+
73+
![Popup to confirm loading debug scripts on a modern page in SharePoint Online](../images/ext-com-accept-debug-scripts.png)
74+
75+
Once you confirm, the page will load with the extensions you specified in your serve configuration.
76+
77+
### Debug extensions by manually building the debug URL
78+
79+
If you're working with a version of the SharePoint Framework older than 1.3.0, and you want to debug an extension on a modern page, you have to manually construct the URL with the required parameters. First, start the local gulp server, by in the command line changing the working directory to your project folder and then executing:
80+
81+
```sh
82+
gulp serve --nobrowser
83+
```
84+
85+
Next, in the web browser, navigate to the modern page, on which you want to test the extension. After the page loaded, copy its URL. Depending on the type of extension you want to test, there are different parameters that you need to add to the URL.
86+
87+
#### Debug application customizer
88+
89+
To debug an application customizer, to the URL of your modern page, add `?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"<extensionId>":{"___location":"<extensionType>","properties":<propertiesJSON>}}`, for example: `https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{"___location":"ClientSideExtension.ApplicationCustomizer","properties":{"testMessage":"Hello as property!"}}}`.
90+
91+
Following are the query string parameters that you need to add:
92+
93+
Parameter|Description
94+
---------|-----------
95+
`loadSPFX=true`|Ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework does not load unless at least one extension is registered. Because no components are registered, you must explicitly load the framework.
96+
`debugManifestsFile`|Specifies that you want to load SPFx components that are locally served. The loader only looks for components in the app catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries).
97+
`customActions`|Simulates a custom action. When you deploy and register this component in a site, you'll create this **CustomAction** object and describe all the different properties you can set on it.
98+
`key`|Use the GUID of the extension as the key to associate with the custom action. This has to match the ID value of your extension, which is available in the extension manifest.json file.
99+
`___location`|The type of custom action. Use `ClientSideExtension.ApplicationCustomizer` for the Application Customizer extension.
100+
`properties`|An optional JSON object that contains properties that are available via the this.properties member
101+
102+
With the parameters added to the URL, reload the page in the web browser. The page will show a popup asking you to confirm that you now will be loading debug scripts.
103+
104+
![Popup to confirm loading debug scripts on a modern page in SharePoint Online](../images/ext-com-accept-debug-scripts.png)
105+
106+
Once you confirm, the page will load with the extensions you specified in your serve configuration.
107+
108+
#### Debug field customizer
109+
110+
To debug a field customizer, to the URL of your list view page, add `?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"<fieldName>":{"id":"<fieldCustomizerId>","properties":<properties>}}`, for example: `https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Percent":{"id":"45a1d299-990d-4917-ba62-7cb67158be16","properties":{"sampleText":"Hello!"}}}`.
111+
112+
Following are the query string parameters that you need to add:
113+
114+
Parameter|Description
115+
---------|-----------
116+
`loadSPFX=true`|Ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework does not load unless at least one extension is registered. Because no components are registered, you must explicitly load the framework.
117+
`debugManifestsFile`|Specifies that you want to load SPFx components that are locally served. The loader only looks for components in the app catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries).
118+
`fieldCustomizers`|indicates which fields in your list should have their rendering controlled by the Field Customizer. The ID parameter specifies the GUID of the extension that should be used to control the rendering of the field. The properties parameter is an optional text string containing a JSON object that is deserialized into `this.properties` for your extension.
119+
`key`|Use the internal name of the field as the key.
120+
`id`|The GUID of the Field Customizer extension associated with this field.
121+
`properties`|The property values defined in the extension. In this example, `sampleText` is a property defined by the extension.
122+
123+
With the parameters added to the URL, reload the page in the web browser. The page will show a popup asking you to confirm that you now will be loading debug scripts.
124+
125+
![Popup to confirm loading debug scripts on a modern page in SharePoint Online](../images/ext-com-accept-debug-scripts.png)
126+
127+
Once you confirm, the page will load with the extensions you specified in your serve configuration.
128+
129+
#### Debug list view command set
130+
131+
To debug a list view command set, to the URL of your list view page, add `?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"<extensionId>":{"___location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":<properties>}}`, for example: `https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{"___location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":{"sampleTextOne":"One item is selected in the list.","sampleTextTwo":"This command is always visible."}}}`.
132+
133+
Following are the query string parameters that you need to add:
134+
135+
Parameter|Description
136+
---------|-----------
137+
`loadSPFX=true`|Ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework does not load unless at least one extension is registered. Because no components are registered, you must explicitly load the framework.
138+
`debugManifestsFile`|Specifies that you want to load SPFx components that are locally served. The loader only looks for components in the app catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries).
139+
`customActions`|simulates a custom action. You can set many properties on this CustomAction object that affect the look, feel, and ___location of your button; we’ll cover them all later.
140+
`key`|GUID of the extension.
141+
`Location`|Where the commands are displayed. The possible values are: `ClientSideExtension.ListViewCommandSet.ContextMenu`: The context menu of the item(s), `ClientSideExtension.ListViewCommandSet.CommandBar`: The top command set menu in a list or library. `ClientSideExtension.ListViewCommandSet`: Both the context menu and the command bar (corresponds to `SPUserCustomAction.Location="CommandUI.Ribbon"`).
142+
`properties`|An optional JSON object containing properties that are available via the this.properties member.
143+
144+
With the parameters added to the URL, reload the page in the web browser. The page will show a popup asking you to confirm that you now will be loading debug scripts.
145+
146+
![Popup to confirm loading debug scripts on a modern page in SharePoint Online](../images/ext-com-accept-debug-scripts.png)
147+
148+
Once you confirm, the page will load with the extensions you specified in your serve configuration.
149+
150+
## Debug SharePoint Framework web parts on modern SharePoint pages
151+
152+
To test the local versions of your SharePoint Framework client-side web parts on modern SharePoint pages in your tenant, first, start the local gulp server, by changing the working directory to your project folder and executing in the command line:
153+
154+
```sh
155+
gulp serve --nobrowser
156+
```
157+
158+
Next, in the web browser, navigate to the modern page, on which you want to test the web parts. After the page loaded, add to its URL `?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js`, for example: `https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js`. The page will reload and show a popup asking you to confirm that you now will be loading debug scripts.
159+
160+
![Popup to confirm loading debug scripts on a modern page in SharePoint Online](../images/ext-com-accept-debug-scripts.png)
161+
162+
Once you confirm, that you want to load the web parts that you are developing, you can edit the page, and in the toolbox, select any of your local web parts.
163+
164+
![SharePoint toolbox with a local web part highlighted](../images/debug-sharepoint-toolbox-modern-page-local-webpart.png)
165+
166+
### Added value of testing SharePoint Framework web parts on modern pages
167+
168+
When building SharePoint Framework web parts, you can test them using the local workbench. This is not only convenient but also efficient: each time you change something in your code, the local workbench will automatically reload and show your latest changes.
169+
170+
In some cases, like when building web parts that communicate with SharePoint, you cannot use the local SharePoint workbench, because you need access to the SharePoint APIs that can be called only in the context of a SharePoint site. In such cases, rather than using the local workbench, you can use the hosted SharePoint workbench which you can access by adding `/_layouts/15/workbench.aspx` to the URL of your site, for example `https://contoso.sharepoint.com/sites/team-a/_layouts/15/workbench.aspx`.
171+
172+
#### UI constraints
173+
174+
SharePoint Framework workbench conveniently mimics the canvas of modern SharePoint pages. But it doesn't mimic all their aspects. The width of the canvas is different, not all theme colors are reflected, and the workbench doesn't allow you to test the full-bleed experience where a web part spans the full width of the web browser without any horizontal margin or padding.
175+
176+
#### Does it work with other web parts and extensions
177+
178+
Using the SharePoint workbench, you can only test web parts from your solution. But what if you wanted to see how your web part works with other web parts on the page? Testing your local solution on modern pages using the approach outlined in this article, is way more efficient than packaging your project, deploying it to the app catalog and adding the web part to the page.
179+
180+
## See also
181+
182+
- [Debug SharePoint Framework solutions in Visual Studio Code](debug-in-vscode.md)
183+
- [Easily test SharePoint Framework web parts on modern pages (Waldek Mastykarz, Rencore)](https://rencore.com/blog/easily-test-sharepoint-framework-web-parts-modern-pages)
184+
- [Testing and debugging your SPFx solutions in production without causing any impact (Elio Struyf)](https://www.eliostruyf.com/testing-and-debugging-your-spfx-solutions-in-production-without-causing-any-impact/)
185+
- [Scaffold projects by using Yeoman SharePoint generator](toolchain/scaffolding-projects-using-yeoman-sharepoint-generator.md)
186+
- [SharePoint Framework Overview](sharepoint-framework-overview.md)

‎docs/toc.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,11 @@
209209
href: spfx/toolchain/scaffolding-projects-using-yeoman-sharepoint-generator.md
210210
- name: Debugging
211211
href: spfx/debug-in-vscode.md
212+
items:
213+
- name: Debug in Visual Studio Code
214+
href: spfx/debug-in-vscode.md
215+
- name: Debug on modern pages
216+
href: spfx/debug-modern-pages.md
212217
- name: Roadmap
213218
href: spfx/roadmap.md
214219
- name: Known issues and FAQ

0 commit comments

Comments
 (0)