You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Deploy your extension to SharePoint (Hello world part 3)
2
+
# Deploy your extension to SharePoint (Hello World part 3)
3
3
4
-
In this article, you will learn how to deploy your SharePoint Framework Application Customizer to SharePoint and see it working on modern SharePoint pages. This article continues with the hello world extension built in the previous article [Using page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md).
4
+
This article describes how to deploy your SharePoint Framework Application Customizer to SharePoint and see it working on modern SharePoint pages. This article continues with the Hello World extension built in the previous article [Use page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md).
5
5
6
6
Be sure you have completed the procedures in the following articles before you begin:
7
7
8
8
*[Build your first SharePoint Framework Extension (Hello World part 1)](./build-a-hello-world-extension.md)
9
-
*[Using page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md)
9
+
*[Use page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md)
10
10
11
11
You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=P_yWI0WVQIg&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV).
<imgsrc="../../../images/spfx-ext-youtube-tutorial3.png"alt="Screenshot of the YouTube video player for this tutorial" />
15
15
</a>
16
16
17
-
## Package the helloWorld Application Customizer
18
-
In the console window, go to the extension project directory created in [Build your first SharePoint Framework Extension (Hello World part 1)](./build-a-hello-world-extension.md)
17
+
## Package the Hello World Application Customizer
18
+
In the console window, go to the extension project directory created in [Build your first SharePoint Framework Extension (Hello World part 1)](./build-a-hello-world-extension.md).
19
19
20
20
```
21
21
cd app-extension
22
22
```
23
-
If gulp serve is still running, stop it from running by pressing `Ctrl+C`.
23
+
If gulp serve is still running, stop it from running by selecting Ctrl+C.
24
24
25
-
Unlike in **Debug** mode, in order to use an extension on modern SharePoint server-side pages, you need to deploy and register the extension with SharePoint in either `Site collection`, `Site`, or `List` scope. The scope defines where and how the Application Customizer will be active. In this particular scenario, we'll register the Application Customizer using the `Site Collection` scope.
25
+
Unlike in **Debug** mode, to use an extension on modern SharePoint server-side pages, you need to deploy and register the extension with SharePoint in `Site collection`, `Site`, or `List` scope. The scope defines where and how the Application Customizer will be active. In this particular scenario, we'll register the Application Customizer by using the `Site collection` scope.
26
26
27
-
Before we package our solution, we want to include the code needed to automate the extension activation within the site, whenever the solution is installed on the site. In this case, we'll use feature framework elements to perform these actions directly in the solution package, but you could also associate the application customizer to a SharePoint site using REST or CSOM as part of the site provisioning, for example.
27
+
Before we package our solution, we want to include the code needed to automate the extension activation within the site whenever the solution is installed on the site. In this case, we'll use feature framework elements to perform these actions directly in the solution package, but you could also associate the application customizer to a SharePoint site by using REST or CSOM as part of the site provisioning, for example.
28
28
29
-
1. Install the solution package to the site where it should be installed, so that extension manifest is being white listed for execution
30
-
2. Associate the Application Customizer to the planned scope. This can be performed programmatically (CSOM/REST) or by using the feature framework inside of the SharePoint Framework solution package. You'll need to associate the following properties in the `UserCustomAction` object at the site collection, site or list level.
31
-
***ClientSideComponentId:** This is the identifier (GUID) of the Field Customizer, which has been installed in the app catalog.
32
-
***ClientSideComponentProperties:** This is an optional parameter, which can be used to provide properties for the Field Customizer instance
33
-
34
-
> Notice, you can control the requirement to add a solution containing your extension to the site by using `skipFeatureDeployment` setting in **package-solution.json**. Event though you would not require solution to be installed on the site, you'd need to associate **ClientSideComponentId** to specific objects for the extension to be visible.
29
+
1. Install the solution package to the site where it should be installed so that the extension manifest is being white listed for execution.
35
30
36
-
In the following steps, we'll review `CustomAction` definition, which was automatically created for the solution as part of the scaffolding for enabling solution in a site when it's being installed.
31
+
2. Associate the Application Customizer to the planned scope. This can be performed programmatically (CSOM/REST) or by using the feature framework inside of the SharePoint Framework solution package. You'll need to associate the following properties in the `UserCustomAction` object at the site collection, site, or list level.
32
+
***ClientSideComponentId:** This is the identifier (GUID) of the Field Customizer, which has been installed in the app catalog.
33
+
***ClientSideComponentProperties:** This is an optional parameter, which can be used to provide properties for the Field Customizer instance.
34
+
35
+
Note that you can control the requirement to add a solution containing your extension to the site by using the `skipFeatureDeployment` setting in **package-solution.json**. Even though you would not require the solution to be installed on the site, you'd need to associate **ClientSideComponentId** to specific objects for the extension to be visible.
36
+
37
+
In the following steps, we'll review the `CustomAction` definition, which was automatically created for the solution as part of the scaffolding for enabling the solution on a site when it's being installed.
38
+
39
+
1. Return to your solution package in Visual Studio Code (or to your preferred editor).
37
40
38
-
Return to your solution package in Visual Studio Code (or to your preferred editor).
41
+
2. Extend the **sharepoint** folder and **assets** subfolder in the root of the solution to see the existing **elements.xml** file.
39
42
40
-
Extend **sharepoint** folder and **assets** sub folder in the root of the solution to see existing **elements.xml** file.
43
+
41
44
42
-
45
+
<br/>
43
46
44
-
### Review existing elements.xml file for SharePoint definitions
47
+
### Review the existing elements.xml file for SharePoint definitions
45
48
46
-
Review the existing xml structure in the **elements.xml** file. Notice that the **ClientSideComponentId** property has been automatically updated based on the unique Id of your Application Customizer available in the **HelloWorldApplicationCustomizer.manifest.json** file in the **src\extensions\helloWorld** folder.
49
+
Review the existing xml structure in the **elements.xml** file. Note that the **ClientSideComponentId** property has been automatically updated based on the unique ID of your Application Customizer available in the **HelloWorldApplicationCustomizer.manifest.json** file in the **src\extensions\helloWorld** folder.
47
50
48
-
**ClientSideComponentProperties** has been also automatically set with default structure and pass JSON properties for this extension instance. Notice how the JSON is escaped so that we can set it properly within an XML attribute.
51
+
**ClientSideComponentProperties** has also been automatically set with the default structure and JSON properties for this extension instance. Note how the JSON is escaped so that we can set it properly within an XML attribute.
49
52
50
-
Notice that configuration uses the specific ___location of `ClientSideExtension.ApplicationCustomizer` to define that this is an Application Customizer. Since by default this **elements.xml**will be associated to a *Web* scoped feature, this `CustomAction`will be automatically added to the `Web.UserCustomAction` collection in the site where the solution is being installed.
53
+
The configuration uses the specific ___location of `ClientSideExtension.ApplicationCustomizer` to define that this is an Application Customizer. Because this **elements.xml**is associated to a *Web* scoped feature by default, this `CustomAction`is automatically added to the `Web.UserCustomAction` collection in the site where the solution is being installed.
51
54
52
-
To ensure that the configuration matches updates performed in the Application Customizer, update the **ClientSideComponentProperties** as in the below xml structure.
55
+
To ensure that the configuration matches updates performed in the Application Customizer, update the **ClientSideComponentProperties** as in the following xml structure. Note that you should not copy the whole structure because it would cause a mismatch with your **ClientSideComponentId**.
53
56
54
-
> Notice that you should not copy the whole structure, since it would cause a mismatch with your **ClientSideComponentId**.
55
57
56
58
```xml
57
59
<?xml version="1.0" encoding="utf-8"?>
@@ -68,6 +70,8 @@ To ensure that the configuration matches updates performed in the Application Cu
68
70
</Elements>
69
71
```
70
72
73
+
<br/>
74
+
71
75
### Ensure that definitions are taken into account within the build pipeline
72
76
73
77
Open **package-solution.json** from the **config** folder. The **package-solution.json** file defines the package metadata as shown in the following code:
@@ -102,60 +106,62 @@ Open **package-solution.json** from the **config** folder. The **package-solutio
102
106
103
107
```
104
108
105
-
To ensure that **element.xml** file is taken into account while the solution is being packaged, default scaffolding has added needed configuration to define a Feature Framework feature definition for the solution package.
109
+
<br/>
106
110
107
-
## Deploy the extension to SharePoint Online and host JavaScript from local host
108
-
109
-
Now you are ready to deploy the solution to a SharePoint site and to have the `CustomAction` automatically associated on the site level.
111
+
To ensure that the **element.xml** file is taken into account while the solution is being packaged, default scaffolding adds needed configuration to define a feature framework feature definition for the solution package.
110
112
111
-
In the console window, enter the following command to package your client-side solution that contains the extension, so that we get the basic structure ready for packaging:
112
-
113
-
```
114
-
gulp bundle
115
-
```
113
+
## Deploy the extension to SharePoint Online and host JavaScript from local host
116
114
117
-
Next, execute the following command so that the solution package is created:
115
+
Now you are ready to deploy the solution to a SharePoint site and have the `CustomAction` automatically associated on the site level.
118
116
119
-
```
120
-
gulp package-solution
121
-
```
117
+
1. In the console window, enter the following command to package your client-side solution that contains the extension so that we get the basic structure ready for packaging:
122
118
123
-
The command will create the package in the **sharepoint/solution** folder:
119
+
```
120
+
gulp bundle
121
+
```
124
122
125
-
```
126
-
app-extension.sppkg
127
-
```
123
+
2. Execute the following command so that the solution package is created:
128
124
129
-
Next you need to deploy the package that was generated to the App Catalog.
125
+
```
126
+
gulp package-solution
127
+
```
130
128
131
-
Go to your tenant's **App Catalog** and open the **Apps for SharePoint**library.
129
+
The command will create the package in the **sharepoint/solution**folder:
132
130
133
-
Upload or drag and drop the `app-extension.sppkg` located in the **sharepoint/solution** folder to the App Catalog. SharePoint will display a dialog and ask you to trust the client-side solution.
131
+
```
132
+
app-extension.sppkg
133
+
```
134
134
135
-
Notice that we did not update the URLs for hosting the solution for this deployment, so the URL is still pointing to `https://localhost:4321`. Click the **Deploy**button.
135
+
3. You now need to deploy the package that was generated to the App Catalog. To do this, go to your tenant's **App Catalog** and open the **Apps for SharePoint**library.
136
136
137
-
137
+
4. Upload or drag and drop the `app-extension.sppkg` located in the **sharepoint/solution** folder to the App Catalog. SharePoint displays a dialog and asks you to trust the client-side solution.
138
138
139
-
Move back to your console and ensure that the solution is running. If it's not running, execute the following command in the solution folder:
139
+
Note that we did not update the URLs for hosting the solution for this deployment, so the URL is still pointing to `https://localhost:4321`.
140
+
141
+
5. Select the **Deploy** button.
140
142
141
-
```
142
-
gulp serve --nobrowser
143
-
```
143
+
144
144
145
-
Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package.
145
+
6. Move back to your console and ensure that the solution is running. If it's not running, execute the following command in the solution folder:
146
+
147
+
```
148
+
gulp serve --nobrowser
149
+
```
150
+
151
+
7. Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package.
146
152
147
-
Choose the gear icon on the top navigation bar on the right and choose**Add an app** to go to your Apps page.
153
+
8. Select the gear icon on the top navigation bar on the right, and then select**Add an app** to go to your Apps page.
148
154
149
-
In the **Search** box, enter '**app**' and press *Enter* to filter your apps.
155
+
9.In the **Search** box, enter **app**, and then select Enter to filter your apps.
150
156
151
-
157
+
152
158
153
-
Choose the **app-extension-client-side-solution** app to install the solution on the site. When the installation is completed, refresh the page by pressing**F5**.
159
+
10. Select the **app-extension-client-side-solution** app to install the solution on the site. When the installation is completed, refresh the page by selecting**F5**.
154
160
155
161
When the application has been successfully installed, you can see the header and footer being rendered just like with the debug query parameters.
156
162
157
163
158
164
159
165
## Next steps
160
166
161
-
Congratulations, you have deployed an extension to a modern SharePoint page from the app catalog! You can continue building out your Hello World extension in the next topic, [Hosting extension from Office 365 CDN (Hello world part 4)](./hosting-extension-from-office365-cdn.md), where you will learn how to deploy and load the extension assets from a CDN instead of localhost.
167
+
Congratulations, you have deployed an extension to a modern SharePoint page from the app catalog! You can continue building out your Hello World extension in the next topic, [Host extension from Office 365 CDN (Hello World part 4)](./hosting-extension-from-office365-cdn.md), where you will learn how to deploy and load the extension assets from a CDN instead of from localhost.
0 commit comments