Skip to content

Commit 9127d17

Browse files
andrewconnellandrewconnell
committed
Update SPFx debugging pages
- updated markdown formatting - Fixed "spfx" => "SPFx" - Added additional details on how to disable automatic loading of debug scripts (ref SharePoint#5385)
1 parent 3a3581f commit 9127d17

File tree

1 file changed

+39
-36
lines changed

1 file changed

+39
-36
lines changed

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

Lines changed: 39 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Debug SharePoint Framework solutions on modern SharePoint pages
33
description: Guidance on how to debug SharePoint Framework solutions on modern SharePoint pages
4-
ms.date: 04/21/2020
4+
ms.date: 05/09/2020
55
ms.prod: sharepoint
66
localization_priority: Priority
77
---
@@ -59,13 +59,13 @@ When you add a new SharePoint Framework extension to your project, the SharePoin
5959

6060
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:
6161

62-
```sh
62+
```shell
6363
gulp serve --config=<name>
6464
```
6565

6666
for example:
6767

68-
```sh
68+
```shell
6969
gulp serve --config=helloWorld
7070
```
7171

@@ -75,11 +75,15 @@ After running this command, gulp will start your web browser with the modern pag
7575

7676
Once you confirm, the page will load with the extensions you specified in your serve configuration.
7777

78+
### Disabling debug scripts
79+
80+
By default, when debug scripts are enabled and allowed once on a page, they will be allowed throughout the browser session. To disable the debug scripts from loading without ending your browser session or manually deleting the session data, include the URL parameter `reset=true` in the request.
81+
7882
### Debug extensions by manually building the debug URL
7983

8084
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:
8185

82-
```sh
86+
```shell
8387
gulp serve --nobrowser
8488
```
8589

@@ -91,14 +95,14 @@ To debug an Application Customizer, to the URL of your modern page, add `?loadSP
9195

9296
Following are the query string parameters that you need to add:
9397

94-
Parameter|Description
95-
---------|-----------
96-
`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.
97-
`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).
98-
`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.
99-
`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.
100-
`___location`|The type of custom action. Use `ClientSideExtension.ApplicationCustomizer` for the Application Customizer extension.
101-
`properties`|An optional JSON object that contains properties that are available via the this.properties member
98+
| Parameter | Description |
99+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
100+
| `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. |
101+
| `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). |
102+
| `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. |
103+
| `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. |
104+
| `___location` | The type of custom action. Use `ClientSideExtension.ApplicationCustomizer` for the Application Customizer extension. |
105+
| `properties` | An optional JSON object that contains properties that are available via the this.properties member |
102106

103107
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.
104108

@@ -112,14 +116,14 @@ To debug a field customizer, to the URL of your list view page, add `?loadSPFX=t
112116

113117
Following are the query string parameters that you need to add:
114118

115-
Parameter|Description
116-
---------|-----------
117-
`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.
118-
`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).
119-
`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.
120-
`key`|Use the internal name of the field as the key.
121-
`id`|The GUID of the Field Customizer extension associated with this field.
122-
`properties`|The property values defined in the extension. In this example, `sampleText` is a property defined by the extension.
119+
|Parameter|Description|
120+
|---------|-----------|
121+
|`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.|
122+
|`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).|
123+
|`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.|
124+
|`key`|Use the internal name of the field as the key.|
125+
|`id`|The GUID of the Field Customizer extension associated with this field.|
126+
|`properties`|The property values defined in the extension. In this example, `sampleText` is a property defined by the extension.|
123127

124128
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.
125129

@@ -133,14 +137,14 @@ To debug a list view command set, to the URL of your list view page, add `?loadS
133137

134138
Following are the query string parameters that you need to add:
135139

136-
Parameter|Description
137-
---------|-----------
138-
`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.
139-
`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).
140-
`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.
141-
`key`|GUID of the extension.
142-
`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"`).
143-
`properties`|An optional JSON object containing properties that are available via the this.properties member.
140+
| Parameter | Description |
141+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
142+
| `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. |
143+
| `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). |
144+
| `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. |
145+
| `key` | GUID of the extension. |
146+
| `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"`). |
147+
| `properties` | An optional JSON object containing properties that are available via the this.properties member. |
144148

145149
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.
146150

@@ -152,7 +156,7 @@ Once you confirm, the page will load with the extensions you specified in your s
152156

153157
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:
154158

155-
```sh
159+
```shell
156160
gulp serve --nobrowser
157161
```
158162

@@ -180,26 +184,25 @@ Using the SharePoint workbench, you can only test web parts from your solution.
180184

181185
## Debug SharePoint Framework web parts -- an alternative approach
182186

183-
If you build your spfx webpart solution without the --ship parameter as following
187+
If you build your SPFx webpart solution without the --ship parameter as following
184188

185-
```sh
189+
```shell
186190
gulp bundle
187191
gulp package-solution
188192
```
189193

190-
the packages generated will reference the code from your local computer (https://localhost:4321). You can deploy the solution to the app catalog as you normally would.
194+
the packages generated will reference the code from your local computer (https://localhost:4321). You can deploy the solution to the app catalog as you normally would.
191195

192-
You can then start your local server by running
196+
You can then start your local server by running
193197

194-
```sh
198+
```shell
195199
gulp serve --nobrowser
196200
```
197201

198-
Now you can go back to a SharePoint site where the solution has been deployed and add the webparts to any page -- modern or classic-- and the webpart code will be loaded from your local development environment. You can debug your webparts just as you would if you ran 'gulp serve' and added your webpart to the workbench.
202+
Now you can go back to a SharePoint site where the solution has been deployed and add the webparts to any page, modern or classic, and the webpart code will be loaded from your local development environment. You can debug your webparts just as you would if you ran 'gulp serve' and added your webpart to the workbench.
199203

200204
This approach should only be used when you are in development mode. If you deploy an app to the app catalog that points to your local host, it will fail to run if your development environment is not running.
201205

202-
203206
## See also
204207

205208
- [Debug SharePoint Framework solutions in Visual Studio Code](debug-in-vscode.md)

0 commit comments

Comments
 (0)