diff --git a/docs/general-development/how-to-access-an-external-data-source-from-a-udf.md b/docs/general-development/how-to-access-an-external-data-source-from-a-udf.md index 93dfbf263..0d6affacb 100644 --- a/docs/general-development/how-to-access-an-external-data-source-from-a-udf.md +++ b/docs/general-development/how-to-access-an-external-data-source-from-a-udf.md @@ -1,7 +1,7 @@ --- title: Access an external data source from a UDF description: This example shows how to access an external database from a user-defined function (UDF). -ms.date: 09/25/2017 +ms.date: 04/22/2026 keywords: how to,howdoi,howto,UDF f1_keywords: - how to,howdoi,howto,UDF @@ -12,6 +12,9 @@ ms.localizationpriority: medium # Access an external data source from a UDF +> [!IMPORTANT] +> Excel Services is a SharePoint Server (on-premises) feature. Excel Services is not supported in SharePoint Online. Use [Excel Online in Microsoft 365](https://www.microsoft.com/microsoft-365) instead. + This example shows how to access an external database from a user-defined function (UDF). @@ -97,7 +100,7 @@ namespace DatabaseAccessUdfTest1 ``` -```VB.net +```vb Imports System Imports System.Collections.Generic diff --git a/docs/general-development/how-to-configure-item-level-security-in-sharepoint.md b/docs/general-development/how-to-configure-item-level-security-in-sharepoint.md index f8e5ffc5c..147ca505d 100644 --- a/docs/general-development/how-to-configure-item-level-security-in-sharepoint.md +++ b/docs/general-development/how-to-configure-item-level-security-in-sharepoint.md @@ -1,40 +1,31 @@ --- title: Configure item-level security in SharePoint description: Learn how to configure item level security when crawling external data with BCS indexing connectors in SharePoint. -ms.date: 09/25/2017 +ms.date: 04/24/2017 ms.assetid: ffd730f2-e7b7-4707-b677-d073da7df7d7 ms.localizationpriority: medium --- - # Configure item-level security in SharePoint Learn how to configure item level security when crawling external data with BCS indexing connectors in SharePoint. +> [!IMPORTANT] +> Business Connectivity Services (BCS) and NTLM-based configurations are primarily supported in SharePoint Server. These approaches are not commonly used in SharePoint Online, where modern authentication and Microsoft Graph-based connectors are preferred. + ## External systems with NTLM authentication - For external systems that support NTLM authentication, the security descriptor can be obtained for each instance of the external content type at crawl time and stored in the content index. During query time, the security descriptor of the user who is submitting the search query is compared to the stored security descriptor to determine whether the user has access to the item. This is the fastest way to perform security trimming on the result set. The metadata model for the external system must indicate where the security descriptor can be found as an external content type field or method. - - - ### External content type field - -Microsoft SharePoint stores the security descriptor if the field of the external content type that contains the descriptor is marked by using the **WindowsSecurityDescriptorField** property, as shown in the following example. - - - +Microsoft SharePoint stores the security descriptor if the field of the external content type that contains the descriptor is marked by using the `WindowsSecurityDescriptorField` property, as shown in the following example. ```XML - - + - Text - SELECT [Identifier] , - [SecurityDescriptor] FROM [Test].[dbo].[Items] WHERE [Identifier] = @Identifier + Text + SELECT [Identifier], [SecurityDescriptor] FROM [Test].[dbo].[Items] WHERE [Identifier] = @Identifier SqlServerTable Items dbo @@ -44,14 +35,14 @@ Microsoft SharePoint stores the security descriptor if the field of the external - - - @@ -64,12 +55,10 @@ Culture=neutral, PublicKeyToken=b77a5c561934e089" IsCollection="true" Name="Secu - + - SecurityDescriptor + SecurityDescriptor @@ -78,48 +67,31 @@ DefaultDisplayName="ReadSecurity"> ``` > [!NOTE] -> ems are limited to a specific size, which access control lists (ACL) can easily exceed. Therefore, the Search connector framework ignores requests to cache items if they contain a security descriptor field. - - - - +> Items are limited to a specific size, which access control lists (ACL) can easily exceed. Therefore, the Search connector framework ignores requests to cache items if they contain a security descriptor field. ### External content type method - -If you have a method defined in the metadata model that returns the security descriptor for an item based on its identifier, you can use the **BinarySecurityDescriptorAccessor** method stereotype, as shown in the following example. - - - +If you have a method defined in the metadata model that returns the security descriptor for an item based on its identifier, you can use the `BinarySecurityDescriptorAccessor` method stereotype, as shown in the following example. ```XML - - + - + - + - + - SecurityDescriptor + SecurityDescriptor @@ -133,31 +105,16 @@ ReturnTypeDescriptorLevel="0"> ``` The following code is the method signature for the method that is specified in the previous example. - - - - - ```csharp - -Public static Byte[]GetItemSecurity (string id) -{ - -} +Public static Byte[]GetItemSecurity (string id) { } ``` - ## External systems with authentication schemes that can be mapped to NTLM authentication - -If the external system does not support NTLM authentication, but the external system users can be mapped to Windows users by using a mapping table, you can use the approach described in the previous two code examples to provide item level security. For this to work, the web service or Windows Communication Foundation (WCF) service exposed by the external system must include a method that converts the external system users to Windows users internally, and then returns a Windows security descriptor for each URL. The following example shows how you could code this method. - - - +If the external system does not support NTLM authentication, but the external system users can be mapped to Windows users by using a mapping table, you can use the approach described in the previous two code examples to provide item level security. For this to work, the web service or Windows Communication Foundation (WCF) service exposed by the external system must include a method that converts the external system users to Windows users internally, and then returns a Windows security descriptor for each URL. The following example shows how you could code this method. ```csharp - /// Returns the security descriptor for a user. /// /// @@ -166,40 +123,27 @@ If the external system does not support NTLM authentication, but the external sy private Byte[] GetSecurityDescriptor(string domain, string username) { - NTAccount acc = new NTAccount(domain, username); - SecurityIdentifier sid = (SecurityIdentifier)acc.Translate(typeof(SecurityIdentifier)); - CommonSecurityDescriptor sd = new CommonSecurityDescriptor(false, false, ControlFlags.None, -sid, null, null, null); - sd.SetDiscretionaryAclProtection(true, false); - -//Deny access to all users. - SecurityIdentifier everyone = new SecurityIdentifier(WellKnownSidType.WorldSid, null); - sd.DiscretionaryAcl.RemoveAccess(AccessControlType.Allow, everyone, -unchecked((int)0xffffffffL), InheritanceFlags.None, PropagationFlags.None); + NTAccount acc = new NTAccount(domain, username); + SecurityIdentifier sid = (SecurityIdentifier)acc.Translate(typeof(SecurityIdentifier)); + CommonSecurityDescriptor sd = new CommonSecurityDescriptor(false, false, ControlFlags.None, sid, null, null, null); + sd.SetDiscretionaryAclProtection(true, false); + + //Deny access to all users. + SecurityIdentifier everyone = new SecurityIdentifier(WellKnownSidType.WorldSid, null); + sd.DiscretionaryAcl.RemoveAccess(AccessControlType.Allow, everyone, unchecked((int)0xffffffffL), InheritanceFlags.None, PropagationFlags.None); -//Grant full access to a specified user. - sd.DiscretionaryAcl.AddAccess(AccessControlType.Allow, sid, + //Grant full access to a specified user. + sd.DiscretionaryAcl.AddAccess(AccessControlType.Allow, sid, unchecked((int)0xffffffffL), InheritanceFlags.None, PropagationFlags.None); - - byte[] secDes = new Byte[sd.BinaryLength]; - sd.GetBinaryForm(secDes, 0); - return secDes; + byte[] secDes = new Byte[sd.BinaryLength]; + sd.GetBinaryForm(secDes, 0); + + return secDes; } ``` - ## See also - - - -- [Search connector framework in SharePoint](search-connector-framework-in-sharepoint.md) - - -- [Implementing a BinarySecurityDescriptorAccessor](https://msdn.microsoft.com/library/6cf70490-dd3c-49cd-bb13-ed33e938435d%28Office.15%29.aspx) - - -- [Enhancing the BDC model file for Search in SharePoint](enhancing-the-bdc-model-file-for-search-in-sharepoint.md) - - - +- [Search connector framework in SharePoint](search-connector-framework-in-sharepoint.md) +- [Implementing a BinarySecurityDescriptorAccessor](/previous-versions/office/developer/sharepoint-2010/ff464369(v=office.14)) +- [Enhancing the BDC model file for Search in SharePoint](enhancing-the-bdc-model-file-for-search-in-sharepoint.md) diff --git a/docs/general-development/how-to-create-external-event-receivers.md b/docs/general-development/how-to-create-external-event-receivers.md index 5f251366f..42d156a00 100644 --- a/docs/general-development/how-to-create-external-event-receivers.md +++ b/docs/general-development/how-to-create-external-event-receivers.md @@ -1,127 +1,76 @@ --- title: Create external event receivers description: Learn the steps for creating external event receivers for on-premises installations of Business Connectivity Services (BCS) external lists. -ms.date: 09/25/2017 +ms.date: 04/24/2017 ms.assetid: c6d5f486-6247-47f9-9876-fab12f13342f ms.localizationpriority: medium --- - # Create external event receivers Learn the steps for creating external event receivers for on-premises installations of Business Connectivity Services (BCS) external lists. -External event receivers are classes that enable SharePoint Add-ins to respond to events that occur to SharePoint items, such as lists or list items. For example, you can respond to list events, such as adding or removing a field; list item events, such as adding or removing a list item or attachment to a list item; or web events, such as adding or deleting a site or site collection. You can add a remote event receiver to an existing Visual Studio solution that contains an SharePoint Add-in. - - - +> [!IMPORTANT] +> SharePoint Add-ins are deprecated. This content applies to on-premises SharePoint Server only. + +External event receivers are classes that enable SharePoint Add-ins to respond to events that occur to SharePoint items, such as lists or list items. For example, you can respond to list events, such as adding or removing a field; list item events, such as adding or removing a list item or attachment to a list item; or web events, such as adding or deleting a site or site collection. You can add a remote event receiver to an existing Visual Studio solution that contains a SharePoint Add-in. -This article accompanies the code sample [SharePoint: Create a remote event receiver for external data](https://code.msdn.microsoft.com/office/SharePoint-2013-Create-a-095c594c). It shows how to create all the components needed to configure and use external system event notifications. -In this example, you will do the following: - - - +This article comes with the original MSDN code sample for creating a remote event receiver for external data. It shows how to create all the components needed to configure and use external system event notifications. + +> [!NOTE] +> The original MSDN code sample referenced in this article is no longer available. All required steps and code snippets are included here. +In this example, you'll do the following: 1. Create an external system based on the Northwind sample database - - -2. Expose the sample data through OData by creating a Windows Communication Foundation (WCF) service. - - -3. Create a polling service that will monitor for changes in the data and notify SharePoint of those changes. - - -4. Create an external event receiver that executes when items are added to the external data and, as a result, creates a new list item on a notifications list. - - - -## Prerequisites and system set up - - -To complete this example, you will need the following prerequisites: - - - - -- Visual Studio 2012 - - -- Office Developer Tools for Visual Studio 2013 - - +1. Expose the sample data through OData by creating a Windows Communication Foundation (WCF) service. +1. Create a polling service that will monitor for changes in the data and notify SharePoint of those changes. +1. Create an external event receiver that executes when items are added to the external data and, as a result, creates a new list item on a notifications list. + +## Prerequisites and system setup + +To complete this example, you'll need the following prerequisites: + +- Visual Studio 2022 +- Office Developer Tools for Visual Studio 2022 - SQL Server - - - SharePoint - - -- Internet Information Services 7.0 - - +- Internet Information Services - Northwind sample database - - ## Build the components for external systems - The biggest part of the configuration actually happens on the external system. For external event receivers to work correctly, the following components must be present and working on the external system: - - - - **Subscription store:** A table that contains information about the subscribers that want to be notified of changes to the external data. - - - **Changes store:** A table that is used to store the changes to the data items. It functions as temporary storage only because the polling service deletes the item in the table when notifications are sent back to subscribers in SharePoint. - - - **Polling service:** Required in this scenario as a means of checking when data has been changed and submitted to the change table. The polling service queries the change table and assembles a notification package that is sent to the SharePoint delivery address (REST endpoint) stored in the subscription store. - - - **OData WCF Data Service:** To expose the data from the external system's database, you have to create a WCF service. This service, running on Internet Information Services (IIS), provides the RESTful interface and OData feed that is needed for this scenario. - - ## Set up the external system - The first task is to set up the external system. - - - ### Attach the Northwind sample database The first part of preparing the back-end system is to add the Northwind sample database to a running instance of SQL Server. If you already have the Northwind sample database installed, you can run the scripts in the following section to create the additional objects needed for external eventing notifications to work. - - - -However, if you don't have Northwind installed, see [Installing the Northwind Sample Database](https://msdn.microsoft.com/library/2f92cfc3-6310-4327-b2f2-8610f7385c86%28Office.15%29.aspx). - - - -The database is also included with the code sample: [SharePoint: Create a remote event receiver for external data](https://code.msdn.microsoft.com/office/SharePoint-2013-Create-a-095c594c). - - - + +However, if you don't have Northwind installed, see [Installing the Northwind Sample Database](/previous-versions/visualstudio/visual-studio-2012/ff851969(v=vs.110)). ### Create the subscription store When the Northwind database is installed, open a new query window and execute the following script. - - - - -``` +```sql USE [Northwind] GO + SET ANSI_NULLS ON GO + SET QUOTED_IDENTIFIER ON GO + CREATE TABLE [dbo].[EntitySubscribe]( [SubscriptionId] [int] IDENTITY(1,1) NOT NULL, [EntityName] [nvarchar](250) NULL, @@ -130,29 +79,18 @@ CREATE TABLE [dbo].[EntitySubscribe]( [UserId] [nvarchar](50) NULL, [SubscribeTime] [timestamp] NULL, [SelectColumns] [nvarchar](10) NULL, - CONSTRAINT [PK_Subscribe] PRIMARY KEY CLUSTERED -( - [SubscriptionId] ASC -)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY] + CONSTRAINT [PK_Subscribe] PRIMARY KEY CLUSTERED ([SubscriptionId] ASC) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY] ) ON [PRIMARY] - GO ``` This creates a table in the Northwind database named EntitySubscribe. This serves as the subscription store referred to earlier. - - - ### Create the change store Run the following script to create the change table that will record changes to the data in the Customers table. - - - - -``` +```sql USE [Northwind] GO @@ -176,35 +114,19 @@ CREATE TABLE [dbo].[Customers_Updates]( [Fax] [nvarchar](24) NULL, [TimeAdded] [datetime] NULL, [EventType] [int] NULL, - CONSTRAINT [PK_Customers_Updates] PRIMARY KEY CLUSTERED -( - [CustomerID] ASC -)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY] -) ON [PRIMARY] - + CONSTRAINT [PK_Customers_Updates] PRIMARY KEY CLUSTERED ([CustomerID] ASC)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] GO ``` This adds a table named Customers_Updates that stores the information about the record that was added to the Customers table. - - - ### Create the change trigger The change trigger is fired when changes happen to the Customers table. Whenever a record is added to Customers, SQL Server executes the trigger, which inserts a new record in the Customers_Updates table with the information about the record. - - - -To create the trigger, execute the following query. - - - - +To create the trigger, execute the following query. -``` - +```sql USE [Northwind] GO @@ -217,7 +139,7 @@ GO CREATE trigger [dbo].[Customer_insupd] on [dbo].[Customers] for INSERT AS -DECLARE +DECLARE @CustomerID nchar(5), @CompanyName nvarchar(40), @ContactName nvarchar(30) , @@ -228,18 +150,18 @@ DECLARE @PostalCode nvarchar(10) , @Country nvarchar(15) , @Phone nvarchar(24) , - @Fax nvarchar(24), + @Fax nvarchar(24), @TimeAdded datetime, @EventType int - + Select @CustomerID = CustomerId, @CompanyName=CompanyName, @ContactName=ContactName, @ContactTitle=ContactTitle, @Address=Address, @City=City, @Region=Region, @PostalCode =PostalCode, @Country=Country, - @Phone=Phone,@Fax=Fax,@EventType=1 + @Phone=Phone,@Fax=Fax,@EventType=1 from inserted - - insert into Customers_Updates + + insert into Customers_Updates (CustomerId,CompanyName, ContactName, ContactTitle, Address, City, Region, @@ -250,27 +172,18 @@ DECLARE @Address, @City, @Region, @PostalCode,@Country, @Phone,@Fax,SYSDATETIME(),@EventType) - -GO +GO ``` > [!NOTE] -> f you are using your own custom stored procedures as defined in your BDC model, you might also want to create the delete and update triggers. The additional triggers are not be covered as part of this scenario. - - - - +> If you're using your own custom-stored procedures as defined in your BDC model, you might also want to create the delete and update triggers. The additional triggers are not covered as part of this scenario. ### Create the stored procedures -If you are using direct table access with Business Connectivity Services, these procedures won't be necessary. However, if you are defining your own procedures and custom code on the external system, you might want to add these to allow access to the table from SQL Server. - - - - -``` +If you're using direct table access with Business Connectivity Services, these procedures won't be necessary. However, if you're defining your own procedures and custom code on the external system, you might want to add these to allow access to the table from SQL Server. +```sql // DeleteEventRecords stored procedure USE [Northwind] GO @@ -280,27 +193,19 @@ GO SET QUOTED_IDENTIFIER ON GO - CREATE PROCEDURE [dbo].[proc_DeleteEventRecords] @CustomerID nchar(5), @EventType int AS - Delete from Customers_Updates + Delete from Customers_Updates WHERE CustomerID like @CustomerID AND EventType=@EventType GO - ``` The **SubscribeEntity** stored procedure will create a record in the subscription store. - - - - - -``` - -// SubscribeEntity +```sql +// SubscribeEntity USE [Northwind] GO @@ -310,7 +215,7 @@ GO SET QUOTED_IDENTIFIER ON GO -CREATE PROCEDURE [dbo].[SubscribeEntity] +CREATE PROCEDURE [dbo].[SubscribeEntity] @EntityName Varchar(255), @EventType Integer, @DeliveryAddress Varchar(255), @@ -323,128 +228,72 @@ BEGIN SET NOCOUNT ON; -- Insert statements for procedure here - + Insert into EntitySubscribe(EntityName,DeliveryURL,EventType,SelectColumns) values (@EntityName,@DeliveryAddress,@EventType,@SelectColumns) - END GO - ``` - ## Create the OData Service - The OData feed is hosted inside a **WCF Data Service**. This WCF service is then hosted by IIS in a web application. - - - + The following steps create a new ASP.NET WCF data service. - - - ### To create the WCF Data Service application +1. In Visual Studio 2022, on the **File** menu, choose **New**, **Project**. +1. In the **New Project** dialog box, under the Visual C# node, choose the **Web** template, and then choose **ASP.NET Web Application**. +1. Enter NorthwindService as the name of the project, and then choose **OK**. -1. In Visual Studio 2012, on the **File** menu, choose **New**, **Project**. - - -2. In the **New Project** dialog box, under the Visual C# node, choose the **Web** template, and then choose **ASP.NET Web Application**. - - -3. Enter NorthwindService as the name of the project, and then choose **OK**. - - Next, using the Visual Studio wizard, you discover the schema of the data source and use it to create an ADO.NET entity data model. - - - ### To define the data model - 1. In **Solution Explorer**, open the shortcut menu for the ASP.NET project, and choose **Add New Item**. - - -2. In the **Add New Item** dialog box, choose the **Data** template, and then choose **ADO.NET Entity Data Model**. - - -3. For the name of the data model, enter Northwind.edmx. - - -4. In the Entity Data Model Wizard, choose **Generate from Database**, and then choose **Next**. - - -5. Connect the data model to the database by doing one of the following steps: - -1. If you do not have a database connection already configured, choose **New Connection** and create a new connection. For more information, see [How to: Create Connections to SQL Server Databases](https://msdn.microsoft.com/library/360c340d-e5a6-4a7e-a569-e95d500be43d%28Office.15%29.aspx). This SQL Server instance must have the Northwind sample database attached. Choose **Next**. - +1. In the **Add New Item** dialog box, choose the **Data** template, and then choose **ADO.NET Entity Data Model**. +1. For the name of the data model, enter Northwind.edmx. +1. In the Entity Data Model Wizard, choose **Generate from Database**, and then choose **Next**. +1. Connect the data model to the database by doing one of the following steps: +1. If you don't have a database connection already configured, choose **New Connection** and create a new connection. For more information, see [How to: Create Connections to SQL Server Databases](/previous-versions/visualstudio/visual-studio-2008/s4yys16a(v=vs.90)). This SQL Server instance must have the Northwind sample database attached. Choose **Next**. + -or- - - -2. If you have a database connection already configured to connect to the Northwind database, choose that connection from the list of connections, and then choose **Next**. - - -6. On the final page of the wizard, select the check boxes for all tables in the database, and clear the check boxes for views and stored procedures. - - -7. Choose the **Finish** button to close the wizard. - - + +1. If you have a database connection already configured to connect to the Northwind database, choose that connection from the list of connections, and then choose **Next**. +1. On the final page of the wizard, select the check boxes for all tables in the database, and clear the check boxes for views and stored procedures. +1. Choose the **Finish** button to close the wizard. + In the next step, you create the actual service that is hosted by IIS that will provide the means to access external data through Representational State Transfer (REST). - - - ### To create the WCF Data Service - 1. In **Solution Explorer**, open the shortcut menu for your ASP.NET project, and choose **Add New Item**. - - -2. In the **Add New Item** dialog box, choose **WCF Data Service**. - - -3. For the name of the service, enter Northwind. - - -4. In the code for the data service, in the definition of the class that defines the data service, replace the comment `/* TODO: put your data source class name here */` with the type that is the entity container of the data model, which in this case is `NorthwindEntities`. The class definition should look like the following. - +1. In the **Add New Item** dialog box, choose **WCF Data Service**. +1. For the name of the service, enter Northwind. +1. In the code for the data service, in the definition of the class that defines the data service, replace the comment `/* TODO: put your data source class name here */` with the type that is the entity container of the data model, which in this case is `NorthwindEntities`. The class definition should look like the following. + ```csharp - public class Northwind : DataService - ``` - ### To set the security on the service +- You now have to modify the security to allow access to the data from the OData feed by external consumers. When a WCF service is created, all access is denied by default. Make the following changes to the class you created. -- You now have to modify the security to allow access to the data from the OData feed by external consumers. When a WCF service is created, all access is denied by default. Make the following changes to the class you just created. - ```csharp - + config.SetEntitySetAccessRule("*", EntitySetRights.All); config.SetServiceOperationAccessRule("*", ServiceOperationRights.All); ``` - ### Create the Subscribe service operation (optional) -The WCF service can also be coded with a means to handle the Subscribe and Unsubscribe requests from SharePoint. If you choose to create custom stored procedures for your application these will each be handled by a service operation. - - - - **Subscribe**: The Subscribe operation takes the request sent by SharePoint and retrieves the delivery address the event type and the entity. It also has to generate a **subscriptionId** and then record all of these into the database table. - - - - +The WCF service can also be coded with a means to handle the Subscribe and Unsubscribe requests from SharePoint. If you choose to create custom-stored procedures for your application these will each be handled by a service operation. + **Subscribe**: The Subscribe operation takes the request sent by SharePoint and retrieves the delivery address the event type and the entity. It also has to generate a **subscriptionId** and then record all of these into the database table. ```csharp @@ -455,273 +304,208 @@ The WCF service can also be coded with a means to handle the Subscribe and Unsub public string Subscribe(string deliveryUrl, string eventType) { // Generate a new Guid that will function as the subscriptionId. - string subscriptionId = new Guid().ToString(); - - // This sproc will be used to create the subscription in the database. - string subscribeSproc = "SubscribeEntity"; - - // Create connection to database. - using (SqlConnection conn = new SqlConnection(sqlConn)) - { - SqlCommand cmd = new SqlCommand(subscribeSproc, conn); - cmd.Parameters.Add(new SqlParameter("SubscriptionId", subscriptionId)); - cmd.Parameters.Add(new SqlParameter("EntityName", entityName)); - cmd.Parameters.Add(new SqlParameter("EventType", eventType)); - cmd.Parameters.Add(new SqlParameter("DeliveryAddress", deliveryUrl)); - cmd.Parameters.Add(new SqlParameter("SelectColumns", selectColumns)); - - try - { - conn.Open(); - cmd.ExecuteNonQuery(); - } - catch (Exception e) - { - throw e; - } - finally - { - conn.Close(); - } - - return subscriptionId; - } + string subscriptionId = new Guid().ToString(); + + // This sproc will be used to create the subscription in the database. + string subscribeSproc = "SubscribeEntity"; + + // Create connection to database. + using (SqlConnection conn = new SqlConnection(sqlConn)) + { + SqlCommand cmd = new SqlCommand(subscribeSproc, conn); + cmd.Parameters.Add(new SqlParameter("SubscriptionId", subscriptionId)); + cmd.Parameters.Add(new SqlParameter("EntityName", entityName)); + cmd.Parameters.Add(new SqlParameter("EventType", eventType)); + cmd.Parameters.Add(new SqlParameter("DeliveryAddress", deliveryUrl)); + cmd.Parameters.Add(new SqlParameter("SelectColumns", selectColumns)); + + try + { + conn.Open(); + cmd.ExecuteNonQuery(); + } + catch (Exception e) + { + throw e; + } + finally + { + conn.Close(); + } + + return subscriptionId; + } +} ``` > [!NOTE] -> If SQL Server is set up for Windows authentication, it will try to authenticate the request with the App Pool identity. Make sure that the account configured in the App Pool has rights to read and write in the database. - - - - +> If SQL Server is set up for Windows authentication, it will try to authenticate the request with the App Pool identity. Make sure that the account configured in the App Pool has rights to read and write in the database. ## Create the polling service - -The polling service is a Windows service that is responsible for querying the change table and creating and sending notifications to SharePoint or SharePoint Online at the specific delivery address. - - - +The polling service is a Windows service that's responsible for querying the change table and creating and sending notifications to SharePoint or SharePoint Online at the specific delivery address. + Next, you create a new Windows Service project that will be registered on the WCF host machine. Once the project is registered, you can view the running service in the Microsoft Management Console (MMC). - - - ### To create a new project +1. Open Visual Studio 2022. +1. Create a new project using the Windows Service template, name the project PollingService, and choose the **OK** button. +1. When the project is created, open the PollingService.cs file in code view. +1. Add the following code in the newly created class. -1. Open Visual Studio 2012. - - -2. Create a new project using the Windows Service template, name the project PollingService, and choose the **OK** button. - - -3. When the project is created, open the PollingService.cs file in code view. - - -4. Add the following code in the newly created class. - ```csharp - public partial class PollingService : ServiceBase { - string subscriptionStorePath = string.Empty; - - public PollingService() - { - InitializeComponent(); - } - - protected override void OnStart(string[] args) - { - - // This is the timer which fires every minute. - System.Timers.Timer aTimer = new System.Timers.Timer(); - aTimer.Elapsed += new System.Timers.ElapsedEventHandler(SendEventNotification); - aTimer.Interval = 60000; - aTimer.Enabled = true; - } - protected override void OnStop() - {} - - private void SendEventNotification(object sender, EventArgs e) - { + string subscriptionStorePath = string.Empty; + + public PollingService() + { + InitializeComponent(); + } + + protected override void OnStart(string[] args) + { + // This is the timer which fires every minute. + System.Timers.Timer aTimer = new System.Timers.Timer(); + aTimer.Elapsed += new System.Timers.ElapsedEventHandler(SendEventNotification); + aTimer.Interval = 60000; + aTimer.Enabled = true; + } + + protected override void OnStop() + { } + + private void SendEventNotification(object sender, EventArgs e) + { + try + { + List events = itemChangeLookUp(); + triggerEventPerSubscription(events); + } + catch (Exception ex) + { + EventLog.Log = "Application"; + EventLog.Source = ServiceName; + EventLog.WriteEntry("PollingService" + ex.Message, EventLogEntryType.Error); + } + } + + private void triggerEventPerSubscription(List events) + { + foreach (ItemChange itemChangeEvent in events) + { + SendNotification(itemChangeEvent, itemChangeEvent.DeliveryAddress); + string message = string.Format("PollingService.TriggerEventPerSubscription: Notification sent for item {0} of eventType {1}", itemChangeEvent.CustomerId, itemChangeEvent.EventType); + EventLog.Log = "Application"; + EventLog.Source = ServiceName; + EventLog.WriteEntry(message); + } + } + + private List itemChangeLookUp() + { + EventLog.Log = "Application"; + EventLog.Source = ServiceName; + EventLog.WriteEntry("Polling for Item Change"); + List itemChangeList = new List(); + string connectionString = "Data Source=.;Initial Catalog=Northwind;Integrated Security=true"; + + // Provide the query string with a parameter placeholder. + string queryString = "Proc_RetrieveEventRecords"; + + // Specify the parameter value. + int paramValue = -50; + + using (SqlConnection connection = new SqlConnection(connectionString)) + { + SqlCommand command = new SqlCommand(queryString, connection); + command.CommandType = CommandType.StoredProcedure; + command.Parameters.AddWithValue("@TimeSince", paramValue); try { - List events = itemChangeLookUp(); - triggerEventPerSubscription(events); + connection.Open(); + SqlDataReader reader = command.ExecuteReader(); + while (reader.Read()) + { + ItemChange item = new ItemChange(reader["CustomerID"].ToString(), Int32.Parse(reader["EventType"].ToString()), + reader[14].ToString(), reader["DeliveryUrl"].ToString(), reader["CompanyName"].ToString(), + reader["ContactName"].ToString(), reader["ContactTitle"].ToString(), reader["Address"].ToString(), + reader["City"].ToString(), reader["Region"].ToString(), reader["Country"].ToString(), reader["PostalCode"].ToString(), + reader["Phone"].ToString(), reader["Fax"].ToString()); + itemChangeList.Add(item); + } + reader.Close(); } catch (Exception ex) { - EventLog.Log = "Application"; - EventLog.Source = ServiceName; - EventLog.WriteEntry("PollingService" + ex.Message, EventLogEntryType.Error); + EventLog.Log = "Application"; + EventLog.Source = ServiceName; + EventLog.WriteEntry("PollingService : ItemChangeLookup " + ex.Message, EventLogEntryType.Error); } - } - - private void triggerEventPerSubscription(List events) - { - foreach (ItemChange itemChangeEvent in events) - { - SendNotification(itemChangeEvent, itemChangeEvent.DeliveryAddress); - string message = string.Format("PollingService.TriggerEventPerSubscription: Notification sent for item {0} of eventType - {1}", itemChangeEvent.CustomerId, itemChangeEvent.EventType); - EventLog.Log = "Application"; - EventLog.Source = ServiceName; - EventLog.WriteEntry(message); - } - } - - private List itemChangeLookUp() - { - EventLog.Log = "Application"; - EventLog.Source = ServiceName; - EventLog.WriteEntry("Polling for Item Change"); - List itemChangeList = new List(); - string connectionString = "Data Source=.;Initial Catalog=Northwind;Integrated Security=true"; - - // Provide the query string with a parameter placeholder. - string queryString = "Proc_RetrieveEventRecords"; - - // Specify the parameter value. - int paramValue = -50; - - using (SqlConnection connection = new SqlConnection(connectionString)) - { - SqlCommand command = new SqlCommand(queryString, connection); - command.CommandType = CommandType.StoredProcedure; - command.Parameters.AddWithValue("@TimeSince", paramValue); - try - { - connection.Open(); - SqlDataReader reader = command.ExecuteReader(); - while (reader.Read()) - { - ItemChange item = new ItemChange(reader["CustomerID"].ToString(), Int32.Parse(reader["EventType"].ToString()), - reader[14].ToString(), reader["DeliveryUrl"].ToString(), reader["CompanyName"].ToString(), - reader["ContactName"].ToString(),reader["ContactTitle"].ToString(), reader["Address"].ToString(), - reader["City"].ToString(), reader["Region"].ToString(), reader["Country"].ToString(), reader["PostalCode"].ToString(), - reader["Phone"].ToString(), reader["Fax"].ToString()); - itemChangeList.Add(item); - } - reader.Close(); - } - catch (Exception ex) - { - EventLog.Log = "Application"; - EventLog.Source = ServiceName; - EventLog.WriteEntry("PollingService : ItemChangeLookup " + ex.Message, EventLogEntryType.Error); - } - } - string message = string.Format("{0} items changes", itemChangeList.Count); - EventLog.Log = "Application"; - EventLog.Source = ServiceName; - EventLog.WriteEntry(message); - - return itemChangeList; - } - + } + string message = string.Format("{0} items changes", itemChangeList.Count); + EventLog.Log = "Application"; + EventLog.Source = ServiceName; + EventLog.WriteEntry(message); + + return itemChangeList; + } ``` The next step is to build an executable file that can be added to the running services on the OData computer. - - - ### To compile and deploy the polling service - 1. Press F5 to build your project. - - -2. Open the **Command Prompt for VS2012**. - - -3. At the prompt, navigate to your project output location. - - -4. In the Bin directory, find the PollingService.exe file. - - -5. Enter installutil PollingService.exe and press Enter. - - -6. Verify that the service is running by running the Services MMC. - - +1. Open the **Command Prompt for VS2022**. +1. At the prompt, navigate to your project output location. +1. In the Bin directory, find the PollingService.exe file. +1. Enter **installutil PollingService.ex**e and press Enter. +1. Verify that the service is running by running the Services MMC. ## Required SharePoint components - -To complete the whole system, the following components are required on the server that is running SharePoint. - - - +To complete the whole system, the following components are required on the server that's running SharePoint. -- **External content type:** The external content type is basically an XML definition of the external data source. For this scenario, you will use the new autogeneration tools in Visual Studio 2012 to discover the data source and create the external content type automatically. - - +- **External content type:** The external content type is basically an XML definition of the external data source. For this scenario, you'll use the new autogeneration tools in Visual Studio 2022 to discover the data source and create the external content type automatically. - **External event receiver:** The remote or external event receiver is the thing that makes actions on external data changes possible in SharePoint. You can create event receivers for external lists and for entities. - + An event receiver that is created for an external list is similar to other event receivers for SharePoint lists. You create the code and attach it to the list. When an action is performed on the data that is represented by the list, the event receiver executes. - - An event receiver for entities is executed just like a list-based event receiver, except it doesn't need to be attached to a list. It receives notifications the same way, but it doesn't need the interface that is associated with the list-based example. The benefit of this is that you can intercept the notifications programmatically and create code to perform some action. In this scenario, that action is to create a new record in the notifications list - - + + An event receiver for entities is executed just like a list-based event receiver, except it doesn't need to be attached to a list. It receives notifications the same way, but it doesn't need the interface that is associated with the list-based example. The benefit of this is that you can intercept the notifications programmatically and create code to perform some action. In this scenario, that action is to create a new record in the notifications list + - **Notifications list:** The notifications list is a simple SharePoint list that is used to record notifications received from the external system. For each new record added to the external system, a record is created in the notifications list. - - ## Set up the SharePoint components - -Now that you have the external system set up, it's time to move on to creating the other half of the equation. You will now create the components to be hosted on SharePoint. - - - +Now that you have the external system set up, it's time to move on to creating the other half of the equation. You'll now create the components to be hosted on SharePoint. -### To create a new Visual Studio 2012 project +### To create a new Visual Studio 2022 project +1. In Visual Studio 2022, choose **New Project**. +1. Choose the SharePoint app project template. -1. In Visual Studio 2012, choose **New Project**. - - -2. Choose the SharePoint app project template. - - -Office Developer Tools for Visual Studio 2013 added an autogeneration wizard that will discover a data source's schema and then create an external content type from that. - - - +Office Developer Tools for Visual Studio 2022 added an autogeneration wizard that will discover a data source's schema and then create an external content type from that. ### To add a new external content type - - In **Solution Explorer**, open the shortcut menu for the project, and choose **Add**, **Content Types for an External Data Source**. - + This starts the **SharePoint Customization Wizard**, which is used to build the external content type automatically. - + For more information about how to create external content types, see [How to: Create an external content type from an OData source in SharePoint](how-to-create-an-external-content-type-from-an-odata-source-in-sharepoint.md). - - -You will now modify the XML that was generated in the previous step to add a method for Subscribe. This will allow BCS to communicate with the external system when someone subscribes to be notified about external data changes. - - - -### To add the Subscribe method to the external content type XML +You'll now modify the XML that was generated in the previous step to add a method for Subscribe. This will allow BCS to communicate with the external system when someone subscribes to be notified about external data changes. +### To add the Subscribe method to the external content type XML 1. In **Solution Explorer**, find the new node named **External Content Types**. - - -2. Find the **Customers.ect** file, and open it with an XML editor. - - -3. Scroll down to the bottom of the page, and paste the following method into the `` section. - +1. Find the **Customers.ect** file, and open it with an XML editor. +1. Scroll down to the bottom of the page, and paste the following method into the `` section. + ```XML - + /EntitySubscribes @@ -804,18 +588,14 @@ You will now modify the XML that was generated in the previous step to add a met ``` -You will now add client code to allow your list to subscribe to event notifications. - - - +You'll now add client code to allow your list to subscribe to event notifications. ### To add code to the App.js file to initiate the subscription - - In the Scripts folder of your SharePoint Add-in project, open the **App.js** file. Paste the following method into the file. - + ``` - + function SubscribeEntity() { var notificationCallback = new SP.BusinessData.Runtime.NotificationCallback(context, "http://[MACHINE NAME]:8585"); @@ -829,27 +609,17 @@ function SubscribeEntity() ``` To register the event receiver with this script, you have to create a button on the Default.aspx page in your project and call the **SubscribeEntity()** from the **onclick()** method. - - - - Open the Default.aspx page, and add the following HTML. - + ```HTML - + ``` For eventing to work, you must also enable the SharePoint list to accept external events. This is done by turning on the External Events feature. - - - -The following is a script that will turn on the feature using client code. - - - - +The following is a script that will turn on the feature using client code. ```csharp function EnableEventing_Clicked() @@ -874,109 +644,52 @@ function EnableEventing_Clicked() } ``` -Just like with **Subscribe**, you will add a button to the page that will turn on the feature. - - - -Add the following HTML to the Default.aspx page, right below the **Subscribe** button. - - - - +Just like with **Subscribe**, you'll add a button to the page that will turn on the feature. +Add the following HTML to the Default.aspx page, right below the **Subscribe** button. ```HTML - + ``` Next, for this scenario you must add a notifications list that will show the notifications sent by the external system. - - - ### To add the notifications list - 1. In **Solution Explorer**, open the shortcut menu for the project name, and choose **Add**. - - -2. Choose the **List** template, and name the listNotificationList. - - +1. Choose the **List** template, and name the listNotificationList. + To mimic an event receiver that is registered with SharePoint in the global assembly cache, the sample provides a console application that will start listening for changes. When it receives a notification, it adds a list item to the **NotificationList**. - - - ### To start the command-line event receiver - 1. Open the **RemoteEventReceiverConsoleApp**. - - -2. Open the **Program.cs** file, and change the name of your local computer (or the computer where the event receiver will be running). - - -3. Click the **Start** button in Visual Studio to run the console application. - - A command window opens, which indicates that the application has compiled correctly, and it is listening for change notifications from the external system. Leave this window open during this test. - - +1. Open the **Program.cs** file, and change the name of your local computer (or the computer where the event receiver will be running). +1. Select the **Start** button in Visual Studio to run the console application. -### To deploy the app to SharePoint + A command window opens, which indicates that the application has compiled correctly, and it's listening for change notifications from the external system. Leave this window open during this test. +### To deploy the app to SharePoint - Press F5 with Visual Studio open to build and deploy the app. - - ## Test the app - Now you can see the app in action. - - - 1. Browse around the app to see the different lists that represent the data in the external system. - - -2. Click the **Customers** list. - - -3. Add a new customer. - - -4. View the new list item you just created. - - -5. Go to the notifications list to see that the external system has notified SharePoint of a change to the Customers table. - +1. Select the **Customers** list. +1. Add a new customer. +1. View the new list item you created. +1. Go to the notifications list to see that the external system has notified SharePoint of a change to the Customers table. + Keep in mind that the timer is set to send notifications every one minute. While testing, you might have to wait for a short period before you see the notifications posted. - - ## See also - - - -- [External events and alerts in SharePoint](external-events-and-alerts-in-sharepoint.md) - - -- [How to: Create an add-in-scoped external content type in SharePoint](how-to-create-an-add-in-scoped-external-content-type-in-sharepoint.md) - - -- [Get started using the client object model with external data in SharePoint](get-started-using-the-client-object-model-with-external-data-in-sharepoint.md) - - -- [Business Connectivity Services in SharePoint](business-connectivity-services-in-sharepoint.md) - - -- [What's new in Business Connectivity Services in SharePoint](what-s-new-in-business-connectivity-services-in-sharepoint.md) - - -- [Get started with Business Connectivity Services in SharePoint](get-started-with-business-connectivity-services-in-sharepoint.md) - - - +- [External events and alerts in SharePoint](external-events-and-alerts-in-sharepoint.md) +- [How to: Create an add-in-scoped external content type in SharePoint](how-to-create-an-add-in-scoped-external-content-type-in-sharepoint.md) +- [Get started using the client object model with external data in SharePoint](get-started-using-the-client-object-model-with-external-data-in-sharepoint.md) +- [Business Connectivity Services in SharePoint](business-connectivity-services-in-sharepoint.md) +- [What's new in Business Connectivity Services in SharePoint](what-s-new-in-business-connectivity-services-in-sharepoint.md) +- [Get started with Business Connectivity Services in SharePoint](get-started-with-business-connectivity-services-in-sharepoint.md) diff --git a/docs/general-development/how-to-customize-a-field-type-using-client-side-rendering.md b/docs/general-development/how-to-customize-a-field-type-using-client-side-rendering.md index 493ed2585..bc3e565d3 100644 --- a/docs/general-development/how-to-customize-a-field-type-using-client-side-rendering.md +++ b/docs/general-development/how-to-customize-a-field-type-using-client-side-rendering.md @@ -1,13 +1,11 @@ --- title: Customize a field type using client-side rendering description: Learn how to customize a field type by using the client-side rendering technology in SharePoint. -ms.date: 09/25/2017 +ms.date: 04/24/2017 ms.assetid: 18e32537-d7ed-4fe7-90cf-b6cfab3f85a3 ms.localizationpriority: medium --- - - # Customize a field type using client-side rendering Learn how to customize a field type by using the client-side rendering technology in SharePoint. @@ -15,131 +13,67 @@ Learn how to customize a field type by using the client-side rendering technolog Client-side rendering provides a mechanism that you can use to produce your own output for a set of controls that are hosted in a SharePoint page. This mechanism enables you to use well-known technologies, such as HTML and JavaScript, to define the rendering logic of custom field types. In client-side rendering you can specify your own JavaScript resources and host them in the data storage options available to your farm solution, such as the _layouts folder. > [!IMPORTANT] -> JSLink based customizations (client-side rendering) are not supported in modern experiences. This includes modern lists and libraries, including JSLink support in the list view web parts of the modern pages. Client-side rendering is supported in the classic experiences in SharePoint Online or in on-premises. +> Client-Side Rendering (CSR) and JSLink are deprecated and not supported in modern SharePoint experiences. +> Use SharePoint Framework (SPFx) Field Customizer extensions instead for modern SharePoint Online and supported on-premises environments. ## Prerequisites for using the examples in this article - To follow the steps in this example, you need the following: - - - - Microsoft Visual Studio 2012 - - - Office Developer Tools for Visual Studio 2012 - - - A SharePoint development environment - - + For information about setting up your SharePoint development environment, see [Set up a general development environment for SharePoint](set-up-a-general-development-environment-for-sharepoint.md). - - - ### Core concepts to help you understand client-side rendering for field types The following table lists useful articles that can help you understand the concepts and steps that are involved in a custom action scenario. - - - **Table 1. Core concepts for client-side rendering for field types** - |**Article title**|**Description**| |:-----|:-----| | [Build farm solutions in SharePoint](build-farm-solutions-in-sharepoint.md)
|Learn about developing, packaging, and deploying administrative extensions to SharePoint using farm solutions.
| -| [Custom Field Types](https://msdn.microsoft.com/library/ms446361.aspx)
|Learn about creating custom field types. As you store your business information in SharePoint, there may be times when your data does not conform to the field types that are available in SharePoint FoundationOr, you might just want to customize those field types. Custom fields can include custom data validation and custom field rendering.
| - +| [Custom Field Types](/previous-versions/office/developer/sharepoint-2010/ms446361(v=office.14))
|Learn about creating custom field types. As you store your business information in SharePoint, there may be times when your data doesn't conform to the field types that are available in SharePoint FoundationOr, you might just want to customize those field types. Custom fields can include custom data validation and custom field rendering.
| ## Code example: Customize the rendering process for a custom field type in a view form - Follow these steps to customize the rendering process for a custom field type: - - - 1. Create the farm solution project. - - -2. Add a class for the custom field type. - - -3. Add an XML definition for the custom field type. - - -4. Add a JavaScript file for the rendering logic of the custom field type. - - -Figure 1 shows a view form with a custom-rendered field type. - - - - -**Figure 1. Custom client-side rendered field in a view form** - - - - - - - - - ![Custom client-side rendered field in a View form](../images/CSRFieldType_result.png) - - - +1. Add a class for the custom field type. +1. Add an XML definition for the custom field type. +1. Add a JavaScript file for the rendering logic of the custom field type. -### To create the farm solution project + **Figure 1. Custom client-side rendered field in a view form** + ![Custom client-side rendered field in a View form](../images/CSRFieldType_result.png) +### To create the farm solution project 1. Open Visual Studio 2012 as administrator (right-click the Visual Studio 2012 icon in the **Start** menu, and then choose **Run as administrator** ). - - -2. Create a new project using the **SharePoint Project** template - - Figure 2 shows the location of the **SharePoint Project** template in Visual Studio 2012, under **Templates**, **Visual C#**, **Office SharePoint**, **SharePoint Solutions**. - - - **Figure 2. SharePoint project Visual Studio template** +1. Create a new project using the **SharePoint Project** template - + Figure 2 shows the location of the **SharePoint Project** template in Visual Studio 2012, under **Templates**, **Visual C#**, **Office SharePoint**, **SharePoint Solutions**. - ![SharePoint Project Visual Studio template](../images/SharePointSolutionVSTemplate.png) - + **Figure 2. SharePoint project Visual Studio template** - + ![SharePoint Project Visual Studio template](../images/SharePointSolutionVSTemplate.png) - -3. Provide the URL of the SharePoint website that you want to use for debugging. - - -4. Select the **Deploy as a farm solution** option. - - +1. Provide the URL of the SharePoint website that you want to use for debugging. +1. Select the **Deploy as a farm solution** option. ### To add a class for the custom field type - 1. Right-click the farm solution project and add a new class. Name the class file FavoriteColorFieldType.cs. - - -2. Copy the following code and paste it in the FavoriteColorFieldType.cs file. The code performs the following tasks: - - - Declares a **FavoriteColorField** class that inherits from **SPFieldText**. - - - - Provides two constructors for the **FavoriteColorField** class. - - - - Overrides the **JSLink** property. - - > [!NOTE] - > The JSLink property is not supported on Survey or Events lists. A SharePoint calendar is an Events list. +1. Copy the following code and paste it in the FavoriteColorFieldType.cs file. The code performs the following tasks: + + - Declares a **FavoriteColorField** class that inherits from **SPFieldText**. + - Provides two constructors for the **FavoriteColorField** class. + - Overrides the **JSLink** property. + + > [!NOTE] + > The JSLink property isn't supported on Survey or Events lists. A SharePoint calendar is an Events list. ```csharp using System; @@ -155,33 +89,33 @@ using Microsoft.SharePoint.WebControls; namespace Microsoft.SDK.SharePoint.Samples.WebControls { /// - /// The FavoriteColorField custom field type + /// The FavoriteColorField custom field type /// inherits from SPFieldText. - /// Users can input the color in the field + /// Users can input the color in the field /// just like in any other text field. - /// But the field will provide additional - /// rendering logic when displaying + /// But the field will provide additional + /// rendering logic when displaying /// the field in a view form. /// public class FavoriteColorField : SPFieldText { - // The solution deploys the JavaScript - // file to the CSRAssets folder + // The solution deploys the JavaScript + // file to the CSRAssets folder // in the WFE's layouts folder. - private const string JSLinkUrl = + private const string JSLinkUrl = "~site/_layouts/15/CSRAssets/CSRFieldType.js"; // You have to provide constructors for SPFieldText. public FavoriteColorField( - SPFieldCollection fields, + SPFieldCollection fields, string name) : base(fields, name) { } public FavoriteColorField( - SPFieldCollection fields, - string typename, + SPFieldCollection fields, + string typename, string name) : base(fields, typename, name) { @@ -189,177 +123,119 @@ namespace Microsoft.SDK.SharePoint.Samples.WebControls } /// - /// Override the JSLink property to return the + /// Override the JSLink property to return the /// value of our custom JavaScript file. /// public override string JSLink { get { - return JSLinkUrl; + return JSLinkUrl; } set { - base.JSLink = value; + base.JSLink = value; } } } -} +} ``` - ### To add an XML definition for the custom field type - 1. Right-click the farm solution project, and add a SharePoint mapped folder. In the dialog box, select the **{SharePointRoot}\\Template\\XML** folder. - - -2. Right-click the XML folder created in the last step, and add a new XML file. Name the XML file fldtypes_FavoriteColorFieldType.xml. - - -3. Copy the following markup, and paste it in the XML file. The markup performs the following tasks: - - - Provides type name for the field type. - - - - Specifies the full class name for the field type. This is the class you created in the previous procedure. - - - - Provides additional attributes for the field type. - - +1. Right-click the XML folder created in the last step, and add a new XML file. Name the XML file fldtypes_FavoriteColorFieldType.xml. +1. Copy the following markup, and paste it in the XML file. The markup does the following tasks: + + - Provides type name for the field type. + - Specifies the full class name for the field type. This is the class you created in the previous procedure. + - Provides additional attributes for the field type. + ```XML - - - - FavoriteColorField - Favorite color field - Favorite color field - Microsoft.SDK.SharePoint.Samples.WebControls.FavoriteColorField, $SharePoint.Project.AssemblyFullName$ - Text - TRUE - TRUE - TRUE - TRUE - TRUE - TRUE - TRUE - - + + + + FavoriteColorField + Favorite color field + Favorite color field + Microsoft.SDK.SharePoint.Samples.WebControls.FavoriteColorField, $SharePoint.Project.AssemblyFullName$ + Text + TRUE + TRUE + TRUE + TRUE + TRUE + TRUE + TRUE + + ``` ### To add a JavaScript file for the rendering logic of the custom field type - 1. Right-click the farm solution project, and add the SharePoint Layouts mapped folder. Add a new CSRAssets folder to the recently added Layouts folder. - - -2. Right-click the CSRAssets folder that you created in the last step, and add a new JavaScript file. Name the JavaScript file CSRFieldType.js. - - -3. Copy the following code and paste it in the JavaScript file. The code performs the following tasks: - - - Creates a template for the field when it is displayed in a view form. - - - - Registers the template. - - - - Provides the rendering logic for the field type when used displayed in a view form. - - +1. Right-click the CSRAssets folder that you created in the last step, and add a new JavaScript file. Name the JavaScript file CSRFieldType.js. +1. Copy the following code and paste it in the JavaScript file. The code performs the following tasks: + + - Creates a template for the field when it's displayed in a view form. + - Registers the template. + - Provides the rendering logic for the field type when used displayed in a view form. ```javascript (function () { - var favoriteColorContext = {}; - - // You can provide templates for: - // View, DisplayForm, EditForm and NewForm - favoriteColorContext.Templates = {}; - favoriteColorContext.Templates.Fields = { - "FavoriteColorField": { - "View": favoriteColorViewTemplate - } - }; + var favoriteColorContext = {}; + + // You can provide templates for: + // View, DisplayForm, EditForm and NewForm + favoriteColorContext.Templates = {}; + favoriteColorContext.Templates.Fields = { + "FavoriteColorField": { + "View": favoriteColorViewTemplate + } + }; - SPClientTemplates.TemplateManager.RegisterTemplateOverrides( - favoriteColorContext - ); + SPClientTemplates.TemplateManager.RegisterTemplateOverrides(favoriteColorContext); })(); // The favoriteColorViewTemplate provides the rendering logic // the custom field type when it is displayed in the view form. function favoriteColorViewTemplate(ctx) { - var color = ctx.CurrentItem[ctx.CurrentFieldSchema.Name]; - return "     " + color; + var color = ctx.CurrentItem[ctx.CurrentFieldSchema.Name]; + return "     " + color; } ``` ### To build and run the solution - 1. Press the F5 key. - - > [!NOTE] - > When you press F5, Visual Studio builds the solution, deploys the solution, and opens the SharePoint website where the solution is deployed. - -2. Create a custom list and add a new Favorite color field column. - - -3. Add one item to the list, and provide a value for the favorite color column. - - -4. Figure 3 shows the create column page with the new custom field type. - - **Figure 3. Creating a new custom field type column** - - - ![Creating a new custom field type column](../images/CSRFieldType_addcolumn.png) - + > [!NOTE] + > When you press F5, Visual Studio builds the solution, deploys the solution, and opens the SharePoint website where the solution is deployed. - +1. Create a custom list and add a new Favorite color field column. +1. Add one item to the list, and provide a value for the favorite color column. +1. Figure 3 shows the create column page with the new custom field type. - + **Figure 3. Creating a new custom field type column** + ![Creating a new custom field type column](../images/CSRFieldType_addcolumn.png) |**Problem**|**Solution**| |:-----|:-----| -|Field type **FavoriteColorField** is not installed properly. Go to the list settings page to delete this field.
|Execute the following command from an elevated command prompt: **iisreset /noforce**.
**Caution:** If you are deploying the solution to a production environment, wait for an appropriate time to reset the web server using **iisreset /noforce**. | - +|Field type **FavoriteColorField** isn't installed properly. Go to the list settings page to delete this field.
|Execute the following command from an elevated command prompt: **iisreset /noforce**.
**Caution:** If you're deploying the solution to a production environment, wait for an appropriate time to reset the web server using **iisreset /noforce**. | ## Next steps - This article demonstrated how to customize the rendering process for a custom field type. As a next step, you can learn more details about custom field types. To learn more, see the following: - - - - -- [How to: Create a Custom Field Type](https://msdn.microsoft.com/library/bb862248.aspx) - - -- [Walkthrough: Creating a Custom Field Type](https://msdn.microsoft.com/library/bb861799.aspx) - - -- [Customize a list view in SharePoint Add-ins using client-side rendering](https://msdn.microsoft.com/library/8d5cabb2-70d0-46a0-bfe0-9e21f8d67d86%28Office.15%29.aspx) - - + +- [How to: Create a Custom Field Type](/previous-versions/office/developer/sharepoint-2010/bb862248(v=office.14)) +- [Walkthrough: Creating a Custom Field Type](/previous-versions/office/developer/sharepoint-2010/bb861799(v=office.14)). +- [Customize a list view in SharePoint Add-ins using client-side rendering](../sp-add-ins/customize-a-list-view-in-sharepoint-add-ins-using-client-side-rendering.md) ## See also - - - -- [Set up a general development environment for SharePoint](set-up-a-general-development-environment-for-sharepoint.md) - - -- [Build sites for SharePoint](build-sites-for-sharepoint.md) - - -- [Add SharePoint capabilities](add-sharepoint-capabilities.md) - - -- [Build farm solutions in SharePoint](build-farm-solutions-in-sharepoint.md) - - + +- [Set up a general development environment for SharePoint](set-up-a-general-development-environment-for-sharepoint.md) +- [Build sites for SharePoint](build-sites-for-sharepoint.md) +- [Add SharePoint capabilities](add-sharepoint-capabilities.md) +- [Build farm solutions in SharePoint](build-farm-solutions-in-sharepoint.md) diff --git a/docs/general-development/how-to-use-the-closeworkbook-method-call-asynchronously.md b/docs/general-development/how-to-use-the-closeworkbook-method-call-asynchronously.md index a2ee24480..750dd59f4 100644 --- a/docs/general-development/how-to-use-the-closeworkbook-method-call-asynchronously.md +++ b/docs/general-development/how-to-use-the-closeworkbook-method-call-asynchronously.md @@ -1,7 +1,7 @@ --- title: Use the CloseWorkbook method call asynchronously description: When you are using Excel Web Services, it is good practice to close the workbook by calling the CloseWorkbook method if you are finished using the session. This closes the session and allows Excel Services to free resources in a predictable manner. This could potentially improve your server performance and robustness. -ms.date: 09/25/2017 +ms.date: 04/24/2026 keywords: async,how to,howdoi,howto f1_keywords: - async,how to,howdoi,howto @@ -13,6 +13,9 @@ ms.localizationpriority: medium # Use the CloseWorkbook method call asynchronously When you are using Excel Web Services, it is good practice to close the workbook by calling the **CloseWorkbook** method if you are finished using the session. This closes the session and allows Excel Services to free resources in a predictable manner. This could potentially improve your server performance and robustness. + +> [!NOTE] +> This article applies to SharePoint Excel Services, which is deprecated and no longer recommended for new development. Use modern alternatives such as Microsoft Graph Excel API or Office Scripts where possible. @@ -43,7 +46,7 @@ public void CloseWorkbookAsync(string sessionId) End Sub ``` -You don't have to implement the event that is called when the **CloseWorkbookAsync** method is called.You can find the signature in the "Reference.cs" file in your project "Web References" directory. +You don't have to implement the event that is called when the **CloseWorkbookAsync** method is called. You can find the signature in the "Reference.cs" file in your project "Web References" directory. > [!NOTE] > You can find the **CloseWorkbookAsync** method in the proxy class that is generated when you add a Web reference using Microsoft Visual Studio 2005. If you are using Visual Studio 2003, you call the **BeginCloseWorkbook** method to close a workbook asynchronously instead. @@ -96,7 +99,7 @@ namespace SampleApplication // Call the GetCell method // to retrieve a value from a cell. // The cell is in the first row and ninth column. - object[] rangeResult2 = xlservice.GetCell(sessionId, + object[] rangeResult2 = es.GetCell(sessionId, sheetName, 0, 8, false, out outStatus); // Close the workbook asynchronously. @@ -152,7 +155,7 @@ Namespace SampleApplication ' Call the GetCell method ' to retrieve a value from a cell. ' The cell is in the first row and ninth column. - Dim rangeResult2() As Object = xlservice.GetCell(sessionId, sheetName, 0, 8, False, outStatus) + Dim rangeResult2() As Object = es.GetCell(sessionId, sheetName, 0, 8, False, outStatus) ' Close the workbook asynchronously. ' This also closes session. diff --git a/docs/general-development/managed-navigation-in-sharepoint.md b/docs/general-development/managed-navigation-in-sharepoint.md index d5a4cfc42..bd09e4a4e 100644 --- a/docs/general-development/managed-navigation-in-sharepoint.md +++ b/docs/general-development/managed-navigation-in-sharepoint.md @@ -1,254 +1,193 @@ --- title: Managed navigation in SharePoint description: Learn about the taxonomy-driven managed navigation feature in SharePoint. -ms.date: 09/25/2017 +ms.date: 04/24/2017 ms.localizationpriority: medium --- - # Managed navigation in SharePoint - - - ![Conceptual overview topic](../images/mod_icon_badge_conoverview.png) - - - - - - - - - - Learn about the taxonomy-driven managed navigation feature in SharePoint. + +> [!NOTE] +> Managed navigation is a feature of **Classic publishing sites**. It isn't supported in the Modern SharePoint experience. + ## Introducing managed navigation - A well-designed navigation tells your site's users a lot about the business, products, and services that the website offers. By updating the taxonomy behind the navigation, businesses can drive and keep up with change without having to recreate their site navigation in the process. In SharePoint, the managed navigation feature enables you to design site navigation that is driven by managed metadata and create SEO-friendly URLs that are derived from the managed navigation structure. Managed navigation provides an alternative to the traditional SharePoint navigation feature—structured navigation—that is based on the structure of SharePoint. Because managed navigation is driven by taxonomy, you can use it to design site navigation around important business concepts without changing the structure of your sites or site components. - - - ## How managed navigation works - Managed navigation provides a framework for dynamically generated pages and provides an associated SEO-friendly URL. Each generated page is represented in the navigation hierarchy. Instead of requiring separate pages to be authored for each category in the taxonomy, the framework provides a templating and inheritance mechanism that creates the landing pages for each navigation link. You can use the topic pages feature to customize the landing page experience. - - - -Managed navigation APIs are built into the taxonomy and publishing libraries in SharePoint. Managed metadata components like term sets and the term store are used to enable taxonomy-driven navigation for your site. In the .NET server class library, the [Microsoft.SharePoint.Publishing.Navigation](https://msdn.microsoft.com/library/Microsoft.SharePoint.Publishing.Navigation.aspx) namespace contains term, term set, and other class objects that mirror the **Term** class and **TermSet** class in the [Microsoft.SharePoint.Taxonomy](https://msdn.microsoft.com/library/Microsoft.SharePoint.Taxonomy.aspx) navigation namespace, providing methods and properties specifically designed to associate those metadata items with navigation elements. Other classes, like [TaxonomySiteMapNode](https://msdn.microsoft.com/library/Microsoft.SharePoint.Publishing.Navigation.TaxonomySiteMapNode.aspx) , enable you to provide metadata with various site navigation elements, such as site map nodes and other parts of your site's navigation. Other classes enable caching and context for managed navigation. - - - + +Managed navigation APIs are built into the taxonomy and publishing libraries in SharePoint. Managed metadata components like term sets and the term store are used to enable taxonomy-driven navigation for your site. In the .NET server class library, the [Microsoft.SharePoint.Publishing.Navigation](/previous-versions/office/sharepoint-server/ms570756(v=office.15)) namespace contains term, term set, and other class objects that mirror the **Term** class and **TermSet** class in the [Microsoft.SharePoint.Taxonomy](/previous-versions/office/sharepoint-server/ee583437(v=office.15)) navigation namespace, providing methods and properties designed to associate those metadata items with navigation elements. Other classes, like [TaxonomySiteMapNode](/previous-versions/office/sharepoint-server/jj254377(v=office.15)) , enable you to provide metadata with various site navigation elements, such as site map nodes and other parts of your site's navigation. Other classes enable caching and context for managed navigation. + You can display taxonomy-driven navigation links in the Global Navigation. The Global Navigation is a navigation layer with one or more layers that's always present, which often appears at the top of a site and displays the top-level content categories. You can also display these links in the current navigation control that often appears on the left side of a page. The current navigation control represents the next level of hierarchy for the category chosen in Global Navigation, or a set of links that belong to that category. - - - ## Friendly URLs and the managed navigation provider - -When you browse to a SharePoint site for the first time, you may notice that the URL format has changed. Instead of an address with a `/Pages/default.aspx` extension, the page URL ends with only `/`. Managed navigation provides a scheme for friendly URLs that is consistent across site, category, and item pages. - - - +When you browse to a SharePoint site for the first time, you may notice that the URL format has changed. Instead of an address with a `/Pages/default.aspx` extension, the page URL ends with only `/`. Managed navigation provides a scheme for friendly URLs that's consistent across site, category, and item pages. + The managed navigation provider enables this experience. When you navigate to the root of any site that uses the managed navigation provider, the Site Welcome Page setting controls the page that's loaded and displayed in the browser, but the URL you see (and that appears in search results) is rewritten to this friendlier format. - - - + Any page, including your site's Welcome Page, can have a friendly URL. Depending on how you configure your site, most pages automatically get a friendly URL. Friendly URLs can be localized. - - - ## Managed Navigation APIs - -The taxonomy API provides several new methods and properties in SharePoint that you can use to customize terms, term sets, and other metadata elements in the term store for use in site navigation scenarios. These APIs are available in the .NET client, .NET server, Silverlight, and JavaScript programming models. - - - +The taxonomy API provides several new methods and properties in SharePoint that you can use to customize terms, term sets, and other metadata elements in the term store for use in site navigation scenarios. These APIs are available in the .NET client, .NET server and JavaScript programming models. ## Code Example: Customizing managed navigation with the .NET client object model (CSOM) API - When you use the .NET client object model for taxonomy, you can create a new navigation term set if a term store exists for the current site collection, or convert an existing term set into one that supports managed navigation. - - - - - - - - - ```csharp public class NavigationTermSetTests { - public void CreateNavigationTermSet() + public void CreateNavigationTermSet() + { + ClientContext clientContext = new ClientContext(TestConfig.ServerUrl); + + TaxonomySession taxonomySession = TaxonomySession.GetTaxonomySession(clientContext); + taxonomySession.UpdateCache(); + + clientContext.Load(taxonomySession, ts => ts.TermStores); + clientContext.ExecuteQuery(); + + if (taxonomySession.TermStores.Count == 0) + throw new InvalidOperationException("The Taxonomy Service is offline or missing"); + + TermStore termStore = taxonomySession.TermStores[0]; + clientContext.Load(termStore, + ts => ts.Name, + ts => ts.WorkingLanguage); + + // Does the TermSet object already exist? + TermSet existingTermSet; + + // Handles an error that occurs if the return value is null. + ExceptionHandlingScope exceptionScope = new ExceptionHandlingScope(clientContext); + using (exceptionScope.StartScope()) { - ClientContext clientContext = new ClientContext(TestConfig.ServerUrl); - - TaxonomySession taxonomySession = TaxonomySession.GetTaxonomySession(clientContext); - taxonomySession.UpdateCache(); - - clientContext.Load(taxonomySession, ts => ts.TermStores); - clientContext.ExecuteQuery(); - - if (taxonomySession.TermStores.Count == 0) - throw new InvalidOperationException("The Taxonomy Service is offline or missing"); - - TermStore termStore = taxonomySession.TermStores[0]; - clientContext.Load(termStore, - ts => ts.Name, - ts => ts.WorkingLanguage); - - // Does the TermSet object already exist? - TermSet existingTermSet; - - // Handles an error that occurs if the return value is null. - ExceptionHandlingScope exceptionScope = new ExceptionHandlingScope(clientContext); - using (exceptionScope.StartScope()) - { - using (exceptionScope.StartTry()) - { - existingTermSet = termStore.GetTermSet(TestConfig.NavTermSetId); - } - using (exceptionScope.StartCatch()) - { - } - } - clientContext.ExecuteQuery(); - - if (!existingTermSet.ServerObjectIsNull.Value) - { - Log("CreateNavigationTermSet(): Deleting old TermSet"); - existingTermSet.DeleteObject(); - termStore.CommitAll(); - clientContext.ExecuteQuery(); - } - - Log("CreateNavigationTermSet(): Creating new TermSet"); - - // Creates a new TermSet object. - TermGroup siteCollectionGroup = termStore.GetSiteCollectionGroup(clientContext.Site, - createIfMissing: true); - TermSet termSet = siteCollectionGroup.CreateTermSet("Navigation Demo", TestConfig.NavTermSetId, - termStore.WorkingLanguage); - - termStore.CommitAll(); - clientContext.ExecuteQuery(); - - NavigationTermSet navTermSet = NavigationTermSet.GetAsResolvedByWeb(clientContext, - termSet, clientContext.Web, "GlobalNavigationTaxonomyProvider"); - - navTermSet.IsNavigationTermSet = true; - navTermSet.TargetUrlForChildTerms.Value = "~site/Pages/Topics/Topic.aspx"; - - termStore.CommitAll(); - clientContext.ExecuteQuery(); - - NavigationTerm term1 = navTermSet.CreateTerm("Term 1", NavigationLinkType.SimpleLink, Guid.NewGuid()); - term1.SimpleLinkUrl = "http://www.bing.com/"; - - Guid term2Guid = new Guid("87FAA433-4E3E-4500-AA5B-E04330B12ACD"); - NavigationTerm term2 = navTermSet.CreateTerm("Term 2", NavigationLinkType.FriendlyUrl, - term2Guid); - - NavigationTerm childTerm = term2.CreateTerm("Term 2 child", NavigationLinkType.FriendlyUrl, Guid.NewGuid()); - - childTerm.GetTaxonomyTerm().TermStore.CommitAll(); - clientContext.ExecuteQuery(); + using (exceptionScope.StartTry()) + { + existingTermSet = termStore.GetTermSet(TestConfig.NavTermSetId); + } + using (exceptionScope.StartCatch()) + { + } } -} + clientContext.ExecuteQuery(); -``` + if (!existingTermSet.ServerObjectIsNull.Value) + { + Log("CreateNavigationTermSet(): Deleting old TermSet"); + existingTermSet.DeleteObject(); + termStore.CommitAll(); + clientContext.ExecuteQuery(); + } + Log("CreateNavigationTermSet(): Creating new TermSet"); -## Code Example: Customizing managed navigation with the .NET server object model API - + // Creates a new TermSet object. + TermGroup siteCollectionGroup = termStore.GetSiteCollectionGroup(clientContext.Site, + createIfMissing: true); + TermSet termSet = siteCollectionGroup.CreateTermSet("Navigation Demo", TestConfig.NavTermSetId, + termStore.WorkingLanguage); + + termStore.CommitAll(); + clientContext.ExecuteQuery(); + + NavigationTermSet navTermSet = NavigationTermSet.GetAsResolvedByWeb(clientContext, + termSet, clientContext.Web, "GlobalNavigationTaxonomyProvider"); + + navTermSet.IsNavigationTermSet = true; + navTermSet.TargetUrlForChildTerms.Value = "~site/Pages/Topics/Topic.aspx"; -You can use the .NET server taxonomy classes and methods in the [Microsoft.SharePoint.Taxonomy](https://msdn.microsoft.com/library/Microsoft.SharePoint.Taxonomy.aspx) and [Microsoft.SharePoint.Publishing.Navigation](https://msdn.microsoft.com/library/Microsoft.SharePoint.Publishing.Navigation.aspx) namespaces to create a new navigation term set. - - - + termStore.CommitAll(); + clientContext.ExecuteQuery(); - - - + NavigationTerm term1 = navTermSet.CreateTerm("Term 1", NavigationLinkType.SimpleLink, Guid.NewGuid()); + term1.SimpleLinkUrl = "http://www.bing.com/"; + Guid term2Guid = new Guid("87FAA433-4E3E-4500-AA5B-E04330B12ACD"); + NavigationTerm term2 = navTermSet.CreateTerm("Term 2", NavigationLinkType.FriendlyUrl, + term2Guid); + NavigationTerm childTerm = term2.CreateTerm("Term 2 child", NavigationLinkType.FriendlyUrl, Guid.NewGuid()); + + childTerm.GetTaxonomyTerm().TermStore.CommitAll(); + clientContext.ExecuteQuery(); + } +} + +``` + +## Code Example: Customizing managed navigation with the .NET server object model API + +You can use the .NET server taxonomy classes and methods in the [Microsoft.SharePoint.Taxonomy](/previous-versions/office/sharepoint-server/ee583437(v=office.15)) and [Microsoft.SharePoint.Publishing.Navigation](/previous-versions/office/sharepoint-server/ms570756(v=office.15)) namespaces to create a new navigation term set. ```csharp ///Create a navigation term set. using (SPSite site = new SPSite(TestConfig.ServerUrl)) { - using (SPWeb web = site.OpenWeb()) - { - TaxonomySession taxonomySession = new TaxonomySession(site, updateCache: true); + using (SPWeb web = site.OpenWeb()) + { + TaxonomySession taxonomySession = new TaxonomySession(site, updateCache: true); - /// Use the first TermStore object in the list. - if (taxonomySession.TermStores.Count == 0) - throw new InvalidOperationException("The Taxonomy Service is offline or missing"); + /// Use the first TermStore object in the list. + if (taxonomySession.TermStores.Count == 0) + throw new InvalidOperationException("The Taxonomy Service is offline or missing"); - TermStore termStore = taxonomySession.TermStores[0]; + TermStore termStore = taxonomySession.TermStores[0]; - /// Does the TermSet object already exist? - TermSet existingTermSet = termStore.GetTermSet(TestConfig.NavTermSetId); - if (existingTermSet != null) - { - Log("CreateNavigationTermSet(): Deleting old TermSet"); - existingTermSet.Delete(); - termStore.CommitAll(); - } + /// Does the TermSet object already exist? + TermSet existingTermSet = termStore.GetTermSet(TestConfig.NavTermSetId); + if (existingTermSet != null) + { + Log("CreateNavigationTermSet(): Deleting old TermSet"); + existingTermSet.Delete(); + termStore.CommitAll(); + } - Log("CreateNavigationTermSet(): Creating new TermSet"); + Log("CreateNavigationTermSet(): Creating new TermSet"); - /// Create a new TermSet object. - Group siteCollectionGroup = termStore.GetSiteCollectionGroup(site); - TermSet termSet = siteCollectionGroup.CreateTermSet("Navigation Demo", TestConfig.NavTermSetId); + /// Create a new TermSet object. + Group siteCollectionGroup = termStore.GetSiteCollectionGroup(site); + TermSet termSet = siteCollectionGroup.CreateTermSet("Navigation Demo", TestConfig.NavTermSetId); - NavigationTermSet navTermSet = NavigationTermSet.GetAsResolvedByWeb(termSet, web, - StandardNavigationProviderNames.GlobalNavigationTaxonomyProvider); + NavigationTermSet navTermSet = NavigationTermSet.GetAsResolvedByWeb(termSet, web, + StandardNavigationProviderNames.GlobalNavigationTaxonomyProvider); - navTermSet.IsNavigationTermSet = true; - navTermSet.TargetUrlForChildTerms.Value = "~site/Pages/Topics/Topic.aspx"; + navTermSet.IsNavigationTermSet = true; + navTermSet.TargetUrlForChildTerms.Value = "~site/Pages/Topics/Topic.aspx"; - NavigationTerm term1 = navTermSet.CreateTerm("Term 1", NavigationLinkType.SimpleLink); - term1.SimpleLinkUrl = "http://www.bing.com/"; + NavigationTerm term1 = navTermSet.CreateTerm("Term 1", NavigationLinkType.SimpleLink); + term1.SimpleLinkUrl = "http://www.bing.com/"; - Guid term2Guid = new Guid("87FAA433-4E3E-4500-AA5B-E04330B12ACD"); - NavigationTerm term2 = navTermSet.CreateTerm("Term 2", NavigationLinkType.FriendlyUrl, - term2Guid); + Guid term2Guid = new Guid("87FAA433-4E3E-4500-AA5B-E04330B12ACD"); + NavigationTerm term2 = navTermSet.CreateTerm("Term 2", NavigationLinkType.FriendlyUrl, + term2Guid); - /// Verify that the NavigationTermSetView is being applied correctly. - Assert.AreEqual(web.ServerRelativeUrl + "/term-2", term2.GetResolvedDisplayUrl(null).ToString()); + /// Verify that the NavigationTermSetView is being applied correctly. + Assert.AreEqual(web.ServerRelativeUrl + "/term-2", term2.GetResolvedDisplayUrl(null).ToString()); - string expectedTargetUrl = web.ServerRelativeUrl - + "/Pages/Topics/Topic.aspx?TermStoreId=" + termStore.Id.ToString() - + "&TermSetId=" + TestConfig.NavTermSetId.ToString() - + "&TermId=" + term2Guid.ToString(); - Assert.AreEqual(expectedTargetUrl, term2.GetResolvedTargetUrl(null, null).ToString()); + string expectedTargetUrl = web.ServerRelativeUrl + + "/Pages/Topics/Topic.aspx?TermStoreId=" + termStore.Id.ToString() + + "&TermSetId=" + TestConfig.NavTermSetId.ToString() + + "&TermId=" + term2Guid.ToString(); + Assert.AreEqual(expectedTargetUrl, term2.GetResolvedTargetUrl(null, null).ToString()); - NavigationTerm childTerm = term2.CreateTerm("Term 2 child", NavigationLinkType.FriendlyUrl); - Assert.AreEqual(web.ServerRelativeUrl + "/term-2/term-2-child", childTerm.GetResolvedDisplayUrl(null).ToString()); + NavigationTerm childTerm = term2.CreateTerm("Term 2 child", NavigationLinkType.FriendlyUrl); + Assert.AreEqual(web.ServerRelativeUrl + "/term-2/term-2-child", childTerm.GetResolvedDisplayUrl(null).ToString()); - /// Commit changes. - childTerm.GetTaxonomyTerm().TermStore.CommitAll(); - } + /// Commit changes. + childTerm.GetTaxonomyTerm().TermStore.CommitAll(); + } } ``` - ## See also - - - [Content Search web part in SharePoint](content-search-web-part-in-sharepoint.md) - - - diff --git a/docs/general-development/work-with-user-profiles-in-sharepoint.md b/docs/general-development/work-with-user-profiles-in-sharepoint.md index f4ced64de..838390d76 100644 --- a/docs/general-development/work-with-user-profiles-in-sharepoint.md +++ b/docs/general-development/work-with-user-profiles-in-sharepoint.md @@ -1,7 +1,7 @@ --- title: Work with user profiles in SharePoint description: Learn about common programming tasks for working with user profiles in SharePoint. -ms.date: 09/25/2017 +ms.date: 04/22/2026 ms.assetid: 7437a7a8-85cb-4233-84af-1eec30dd54b2 ms.localizationpriority: high --- @@ -23,12 +23,6 @@ User profiles and user profile properties provide information about SharePoint u - .NET client object model - - Silverlight client object model - - - - Mobile client object model - - - JavaScript object model @@ -46,11 +40,7 @@ As a best practice in SharePoint development, use client APIs when you can. Clie -Each API includes a manager object that you use to perform core profile-related tasks. Table 1 shows the manager and other key objects (or REST resources) in the APIs and the class library (or access point) where you can find them. - -> [!NOTE] -> The Silverlight and mobile client object models are not included in Table 1 or Table 2 because they provide the same core functionality as the .NET client object model and use the same signatures. The Silverlight client object model is defined in Microsoft.SharePoint.Client.UserProfiles.Silverlight.dll, and the mobile client object model is defined in Microsoft.SharePoint.Client.UserProfiles.Phone.dll. - +Each API includes a manager object that you use to perform core profile-related tasks. Table 1 shows the manager and other key objects (or REST resources) in the APIs and the class library (or access point) where you can find them. @@ -86,7 +76,7 @@ Table 2 shows common programming tasks for working with user profiles and the me |Get a specific user profile property for a user |CSOM: [GetUserProfilePropertyFor](https://msdn.microsoft.com/library/Microsoft.SharePoint.Client.UserProfiles.PeopleManager.GetUserProfilePropertyFor.aspx)
JSOM: [getUserProfilePropertyFor](https://msdn.microsoft.com/library/da048bfa-54c6-8216-e8ef-09bd84f68d8d%28Office.15%29.aspx)
REST: **GET** [`http:///_api/SP.UserProfiles.PeopleManager/GetUserProfilePropertyFor(accountName=@v,propertyName='PreferredName')?@v='domain\\user'`](https://msdn.microsoft.com/library/10757ed1-6e86-474f-89e0-6dec6aa66a2b%28Office.15%29.aspx#bk_PeopleManagerGetUserProfilePropertyFor)
SSOM: [UserProfile](https://msdn.microsoft.com/library/Microsoft.Office.Server.UserProfiles.UserProfile.aspx) (overloaded) and specify the property name in the indexer| |Get a user profile |CSOM: [GetUserProfile](https://msdn.microsoft.com/library/Microsoft.SharePoint.Client.UserProfiles.ProfileLoader.GetUserProfile.aspx) (returns the [client-side user profile](work-with-user-profiles-in-sharepoint.md#bkmk_NewUserObjects) for the current user only)
JSOM: [getUserProfile](https://msdn.microsoft.com/library/8e30e811-5da1-b6d0-a8b5-befea9b22496%28Office.15%29.aspx) (returns the [client-side user profile](work-with-user-profiles-in-sharepoint.md#bkmk_NewUserObjects) for the current user only)
REST: **POST** [`http:///_api/SP.UserProfiles.ProfileLoader.GetProfileLoader/GetUserProfile`](https://msdn.microsoft.com/library/office/dn790354.aspx#bk_ProfileLoaderGetUserProfile) (returns the [client-side user profile](work-with-user-profiles-in-sharepoint.md#bkmk_NewUserObjects) for the current user only)
SSOM: [GetUserProfile](https://msdn.microsoft.com/library/Microsoft.Office.Server.UserProfiles.UserProfileManager.GetUserProfile.aspx) (overloaded)| |Find out whether a user account exists |CSOM: not implemented
JSOM: not implemented
REST: not implemented
SSOM: [UserExists](https://msdn.microsoft.com/library/Microsoft.Office.Server.UserProfiles.UserProfileManager.UserExists.aspx)| -|Create or change user profiles and user profile properties and attributes
(Client APIs can change the profile picture. See the "Change the user's profile picture" task in this table.) |CSOM: not implemented
JSOM: not implemented
REST: not implemented
SSOM: multiple???see [How to: Work with user profiles and organization profiles by using the server object model in SharePoint](how-to-work-with-user-profiles-and-organization-profiles-by-using-the-server-obj.md)| +|Create or change user profiles and user profile properties and attributes
(Client APIs can change the profile picture. See the "Change the user's profile picture" task in this table.) |CSOM: not implemented
JSOM: not implemented
REST: not implemented
SSOM: multiple - see [How to: Work with user profiles and organization profiles by using the server object model in SharePoint](how-to-work-with-user-profiles-and-organization-profiles-by-using-the-server-obj.md)| |Delete a user profile |CSOM: not implemented
JSOM: not implemented
REST: not implemented
SSOM: [RemoveProfile](https://msdn.microsoft.com/library/Microsoft.Office.Server.UserProfiles.UserProfileManager.RemoveProfile.aspx) or [RemoveUserProfile](https://msdn.microsoft.com/library/Microsoft.Office.Server.UserProfiles.UserProfileManager.RemoveUserProfile.aspx) (overloaded)| |Provision a user's personal site |CSOM: [CreatePersonalSiteEnque](https://msdn.microsoft.com/library/Microsoft.SharePoint.Client.UserProfiles.UserProfile.CreatePersonalSiteEnque.aspx) (overloaded)
JSOM: [createPersonalSiteEnque](https://msdn.microsoft.com/library/f4bcb82d-4048-0b29-9bc6-ce70ead49988%28Office.15%29.aspx) (overloaded)
REST: **POST** [`http:///_api/SP.UserProfiles.ProfileLoader.GetProfileLoader/GetUserProfile/CreatePersonalSiteEnqueue`](https://msdn.microsoft.com/library/10757ed1-6e86-474f-89e0-6dec6aa66a2b%28Office.15%29.aspx#bk_UserProfileCreatePersonalSiteEnque)
SSOM: [CreatePersonalSite()](https://msdn.microsoft.com/library/Microsoft.Office.Server.UserProfiles.UserProfile.CreatePersonalSite.aspx) (overloaded)| |Provision one or more users' personal sites
Available for My Site Host administrators on SharePoint Online only |CSOM: [CreatePersonalSiteEnqueueBulk](what-s-new-for-developers-in-social-and-collaboration-features-in-sharepoint-201.md#bk_CreatePersonalSiteEnqueueBulk)
JSOM: **createPersonalSiteEnqueueBulk**
REST: **POST** [`https://-admin.sharepoint.com/_api/SP.UserProfiles.ProfileLoader.GetProfileLoader/CreatePersonalSiteEnqueueBulk`](https://msdn.microsoft.com/library/dn790354.aspx#bk_ProfileLoaderCreatePersonalSiteEnqueueBulk) and pass a string array of email addresses for the _emailIDs_ parameter (200 characters maximum) in the request body (example: `{'emailIDs':['usera@contoso.onmicrosoft.com','userb@contoso.onmicrosoft.com']}`).
SSOM: **CreatePersonalSiteEnqueueBulk**|