diff --git a/docs/general-development/overview-of-the-sharepoint-mobile-object-model.md b/docs/general-development/overview-of-the-sharepoint-mobile-object-model.md index 334fba6a5..1368fad48 100644 --- a/docs/general-development/overview-of-the-sharepoint-mobile-object-model.md +++ b/docs/general-development/overview-of-the-sharepoint-mobile-object-model.md @@ -8,6 +8,15 @@ ms.localizationpriority: medium # Overview of the SharePoint mobile object model + +> [!IMPORTANT] +> The APIs and technologies described in this article are legacy SharePoint Server capabilities intended for historical reference only. +> +> - Windows Phone 7.5 is no longer supported. +> - Silverlight is deprecated and unsupported in modern browsers. +> - SharePoint Online does not support these mobile object model APIs. +> - Modern SharePoint development uses Microsoft Graph, SharePoint REST APIs, SPFx, and Power Platform solutions instead. + Learn about the new public classes in the SharePoint server object model and Silverlight client object model that are used to develop integrated solutions for SharePoint and Windows Phone 7.5. ## Client object model for mobile Silverlight @@ -21,149 +30,81 @@ All classes in this section are in the **Microsoft.SharePoint.Client** namespace Represents an alternative URL for a web application and the zone to which it applies. - - - ```csharp public class AlternateUrl ``` - - #### Properties **Uri** (read-only) - - Gets the URI of the alternate URL. - - - - - ```csharp public String Uri ``` **UrlZone** (read-only) - - Gets the zone of the alternate URL. - - - - - ``` public UrlZone UrlZone ``` -The UrlZone class is the client object model version of the SPUrlZone class in the server object model. For more information about it, see the [SharePoint 2010 Software Development Kit (SDK)](https://msdn.microsoft.com/library/ee557253.aspx). - - - +The UrlZone class is the client object model version of the SPUrlZone class in the server object model. For more information about it, see the [SharePoint 2010 Software Development Kit (SDK)](/previous-versions/office/developer/sharepoint-2010/ee557253(v=office.14)). ### AuthenticationCompletedEventArgs class Provides data about an **AuthenticationCompleted** event. - - - ```csharp public sealed class AuthenticationCompletedEventArgs : AsyncCompletedEventArgs ``` - - #### Constructors Initializes a new instance of the AuthenticationCompletedEventArgs class. - - - ```csharp public AuthenticationCompletedEventArgs(Exception error, bool canceled, HttpStatusCode userState) ``` **Parameters** - - - - - _error_ is the Exception object if there was an exception thrown in the authentication attempt. - - _canceled_ is true if the authentication attempt was canceled before it could succeed or fail. - - _userState_ is the HttpStatusCode returned by the server. - - #### Properties **HttpStatusCode** (read-only) - - Gets the status returned by the server after an authentication attempt. - - - - - ```csharp public HttpStatusCode HttpStatusCode ``` - - ### AuthenticationStatus enum Specifies the current state of an authentication attempt. - - - - - **NotStarted** - - - **InProgress** - - - **CompletedSuccess** - - - **CompletedException** - - ### Authenticator class Provides methods for authenticating a user on a SharePoint website. - - - - ``` public class Authenticator : ICredentials ``` - - #### Constructors Initializes a new instance of the class. - - - ```csharp public Authenticator() @@ -171,262 +112,115 @@ public Authenticator(Uri uagServerUrl) ``` **Parameters** - - - _uagServerUrl_ is the absolute URL of a United Access Gateway (UAG) server. - - - - - ```csharp public Authenticator(string userName, string password) ``` **Parameters** - - - _userName_ is the name for the credentials. - - - _password_ is the password for the credentials. - - - - - - ```csharp public Authenticator(string userName, string password, string domain) ``` **Parameters** - - - _userName_ is the name for the credentials. - - - _password_ is the password for the credentials. - - - - _domain_ is the name of the domain or computer where the credentials are verified, typically the domain of the current user. - - - - - +_domain_ is the name of the domain or computer where the credentials are verified, typically the domain of the current user. ```csharp public Authenticator(string userName, string password, Uri uagServerUrl) ``` **Parameters** - - - _userName_ is the name for the credentials. - - - _password_ is the password for the credentials. - - - _uagServerUrl_ is the absolute URL of a United Access Gateway (UAG) server. - - - - - ```csharp public Authenticator(string userName, string password, string domain, Uri uagServerUrl) ``` **Parameters** - - - _userName_ is the name for the credentials. - - - _password_ is the password for the credentials. - - - _domain_ is the name of the domain or computer where the credentials are verified, typically the domain of the current user. - - - - _uagServerUrl_ is the absolute URL of a United Access Gateway (UAG) server. - - - +_uagServerUrl_ is the absolute URL of a United Access Gateway (UAG) server. #### Methods **ClearAllApplicationSettings** - - - Clears all cookies, credentials, and UAG settings from the cache. - - - - - ```csharp -public static void ClearAllApplicationSettings +public static void ClearAllApplicationSettings() ``` **ClearAllCookies** - - - Clears all stored cookies and sets the **Status** property of all **Authenticator** objects to **NotStarted**. - - - - - ```csharp public static void ClearAllCookies() ``` **ClearAllCredentials** - - - Clears all credentials from the cache and sets the **Status** property of all **Authenticator** objects to **NotStarted**. - - - - - ```csharp public static void ClearAllCredentials() ``` **GetCredential** - - - Gets a credential object for the specified uri and authentication type. - - - - - ``` public NetworkCredential GetCredential(Uri uri, string authType) ``` **Parameters** - - - - - _uri_ is the URI, including port, for which the client is providing authentication. - - - _authType_ is the type of authentication requested. -This method is only used for anonymous authentication. If _authType_ is not "Basic", an empty object is returned. For more information about the **NetworkCredential** class, see [NetworkCredential Class](https://msdn.microsoft.com/library/system.net.networkcredential.aspx). - - - +This method is only used for anonymous authentication. If _authType_ is not "Basic", an empty object is returned. For more information about the **NetworkCredential** class, see [NetworkCredential Class](/dotnet/api/system.net.networkcredential). **IsRequestUnauthorized** - - - Returns true if the authorization request failed because of an invalid cookie or credentials. - - - - - - ```csharp public static bool IsRequestUnauthorized(ClientRequestFailedEventArgs failedEventArgs) ``` - #### Properties - **AllowSmartRouting** - - - Gets or sets an indicator of whether smart routing is enabled. - - - - - ``` public bool AllowSmartRouting ``` When smart routing is enabled, the **Authenticator** object tries to connect to the server that is running SharePoint and the UAG server and uses whichever responds first as its communication channel. If there is no UAG server, this property is ignored. The default is **true**. If set to **false**, the UAG server is always used. - - **AuthenticatorMode** - - Gets or sets the authentication mode. - - - - - ```csharp public ClientAuthenticationMode AuthenticationMode ``` For more information about the **ClientAuthenticationMode** enum, see later in this document. - - **CookieCachingEnabled** - - - Gets or sets an indicator of whether cookies are cached. - - - - - ``` public bool CookieCachingEnabled ``` If you enable caching of cookies, consider that the cookies expire at some point. If they are expired when **ExecuteQueryAsync** is called, then it fails and the callback for failure runs. Accordingly, if you set this property to true, you must add code to the callback for failure that clears the cache if this happens. Here is an example, where `execQueryArgs` is of the type **ClientRequestFailedEventArgs** passed in the failure callback of **ExecuteQueryAsync**. - - - - - ```csharp if (Authenticator.IsRequestUnauthorized(execQueryArgs)) { @@ -435,161 +229,79 @@ if (Authenticator.IsRequestUnauthorized(execQueryArgs)) ``` **CredentialCachingEnabled** - - - Gets or sets an indicator of whether credentials are cached. - - - - - ```csharp public bool CredentialCachingEnabled ``` **Domain** - - - Gets or sets the domain or computer for the credential, usually this is the domain of the current user. - - - - - ```csharp public string Domain ``` When this property is set to a new value, the **Status** property is set to NotStarted. - - **NavigateBackAfterAuthentication** - - - Gets or sets a indicator of whether the user should be navigated back to the previous page from the login page. - - - - - - ```csharp public bool NavigateBackAfterAuthentication ``` **Password** - - - Gets or sets the password for the credential. - - - - - ```csharp public string Password ``` When this property is set to a new value, the **Status** property is set to **NotStarted**. - - - **PromptOnFailure** - - + **PromptOnFailure** Gets or sets an indicator of whether the user should be prompted to enter a name and password if initial authentication fails. - - - - - ```csharp public bool PromptOnFailure ``` **Status** (read-only) - - - Gets the status of the attempt to authenticate. - - - - - - ```csharp public AuthenticationStatus Status ``` See earlier in this document for information about the **AuthenticationStatus** class. - - **UagServerUrl** - - Gets or sets the URL of the UAG server. - - - - - ```csharp public Uri UagServerUrl ``` - **UserName** - - Gets or sets the user name for the credential. - - - - - ```csharp public string UserName ``` When this property is set to a new value, the **Status** property is set to **NotStarted**. - - - #### Events - **AuthenticationCompleted** - - Raised when the authentication attempt is completed, regardless of whether it succeeded. - - - - - ```csharp public event EventHandler AuthenticationCompleted; ``` - ### ClientAuthenticationMode enum Specifies an authentication mode for an **Authenticator** object. This is an existing enum to which a new value, **BrowserBasedAuthentication** has been added. @@ -605,143 +317,71 @@ Specifies an authentication mode for an **Authenticator** object. This is an exi Provides methods for authenticating a user on a SharePoint website. - - - ```csharp public class ODataAuthenticator : Authenticator ``` - #### Constructors - The constructors are identical to the parent class constructors. For more information, see Authenticator Class earlier in this document. - - - #### Methods **Authenticate** - - - Authenticates a user to the specified website. - - - - - ```csharp public new void Authenticate(Uri serverUrl) ``` The `new` keyword is used because the parent class has an internal method of the same name. - - - #### Properties **CookieContainer** (read-only) - - - Gets a container with the cookies for requests to the website. - - - - - ```csharp public new CookieContainer CookieContainer ``` The `new` keyword is used because the parent class has an internal method of the same name. - - **ResolvedUrl** (read-only) - - Gets the URL that is used for communication to the server that is running SharePoint when an **ODataAuthenticator** is being used. This may be the URL published on the UAG server or, if the **AllowSmartRouting** property is true, this may be the SharePoint intranet URL if it is reached first when the **Authenticate** method is called. - - - - - ```csharp public Uri ResolvedUrl ``` - - ### ServerSettings class Provides a method for getting the Alternate URLs of the web application that contains a website. - - - ```csharp public static class ServerSettings ``` - #### Methods - **GetAlternateUrls** - - - Gets the alternate URLs of the specified website. - - - - - ```csharp public static ClientObjectList GetAlternateUrls(ClientRuntimeContext context) ``` - **Parameters** - - - _context_ is the an object that represents the current client context. - - - See earlier in this document for information about the **AlternateUrl** class. - - - ## Server object model for SharePoint mobility All classes in this section are in the **Microsoft.SharePoint** namespace. Except where specified, these are all available also in the client object model. For classes that begin with "SP", the client object model name has the "SP" removed. In other cases, the client object model name is specified. Member names are the same in the client object model except where specified otherwise. - - - ### GeolocationFieldControl class - (Not available in client object model.) - - Governs the rendering of **SPFieldGeolocation** fields. An object of this type is used as the value of the **FieldRenderingControl** property of a **SPFieldGeolocation** object. - - - - - ```csharp public class GeolocationFieldControl : BaseFieldControl ``` @@ -749,15 +389,10 @@ public class GeolocationFieldControl : BaseFieldControl In connection with this class, note also that there are two rendering templates, one for Display mode and one for New and Edit mode. They are defined in the file %SHAREPOINTROOT%\\TEMPLATE\\ControlTemplates\\DefaultTemplates.ascx. - - #### Fields The following are used to render the field in the New and Edit modes. - - - ```csharp protected TextBox m_latitudeBox; protected TextBox m_longitudeBox; @@ -765,15 +400,10 @@ protected Label m_longitudeLabel; protected Label m_latitudeLabel; ``` - #### Methods No non-derived public properties are introduced with this class. There are standard overrides of some derived methods as indicated in the following table. - - - - |**Method**|**This override???**| |:-----|:-----| |CreateChildControls
|Creates the child controls including a JavaScript map control for Display mode.
| @@ -787,9 +417,6 @@ No non-derived public properties are introduced with this class. There are stand No non-derived public properties are introduced with this class. There are standard overrides of some derived properties as indicated in the following table. - - - |**Property**|**This override...**| |:-----|:-----| |CssClass
|Behaves just like the parent implementation.
| @@ -802,9 +429,6 @@ No non-derived public properties are introduced with this class. There are stand Represents a field (column) that holds a location on the globe defined by longitude, latitude, and possibly altitude. - - - ```csharp public class SPFieldGeolocation : SPField @@ -812,120 +436,54 @@ public class SPFieldGeolocation : SPField In connection with this class, the **Geolocation** field type is defined in % _SHAREPOINTROOT%_\\TEMPLATE\\XML\\fldtypes.xml. - - - #### Constructors (overloaded) - Initializes a new instance of the **SPFieldGeolocation** class. - - - ```csharp public SPFieldGeolocation(SPFieldCollection fields, string fieldName) public SPFieldGeolocation(SPFieldCollection fields, string fieldName, string displayName) ``` **Parameters** - - - - - _fields_ is the collection of field types to which the new field type object is added. - - - _fieldName_ is an internal name of the new field type. - - - _displayName_ is a friendly name of the new field type. - - #### Methods - **GetFieldValueForClientRender** - - - Gets the value of the field so that it can be rendered on the client. - - - - - - ```csharp public override object GetFieldValueForClientRender(SPItem item, SPControlMode mode) ``` Parameters - - - - - _item_ is the current list item. - - - _mode_ is the current rendering mode such as New, Edit, or Display. - **GetJsonClientFormFieldSchema** - - - Gets the field schema as JavaScript Object Notation (JSON). - - - - - ```csharp public override Dictionary GetJsonClientFormFieldSchema(SPControlMode mode) ``` **Parameters** - - - _mode_ is the current rendering mode such as New, Edit, or Display. - - **ValidateAndParseValue** - - - Verifies that the specified list item is not null and then verifies that the string is structured in compliance with Open Geospatial Consortium (OGC) standards and returns it as an object that is castable to the **SPFieldGeolocationValue** type. - - - - - ```csharp public override object ValidateAndParseValue(SPListItem item, string value) ``` **Parameters** - - - - - _item_ is a list item that is to be updated with the value. - - - _value_ is a string representation of a geolocation value. - The following methods are standard overrides of inherited methods that were in SharePoint 2010. The specific information for this class is in the following table. - - - - |**Method**|**This override...**| |:-----|:-----| |GetFieldValue(String s)
|Returns the specified value as an Object that is castable to SPFieldGeolocationValue.
| @@ -936,18 +494,12 @@ The following methods are standard overrides of inherited methods that were in S #### Properties **JSLink** - - - Gets or sets the name of the JavaScript file that renders the fields of the **SPFieldGeolocation** type. -> [!NOTE] -> The JSLink property is not supported on Survey or Events lists. A SharePoint calendar is an Events list. - - - - - +> [!WARNING] +> JSLink customization is deprecated and is not supported in modern SharePoint experiences. Use SharePoint Framework (SPFx) field customizers or column formatting instead. +> +> The JSLink property is also not supported on Survey or Events lists. ```csharp @@ -956,33 +508,16 @@ public override string JSLink The default value is "clienttemplates.js|Geolocationfieldtemplate.js|sp.map.js". - - **FieldRenderingMobileWebControl** - - - Gets the **SPMobileGeolocationField** object that renders the field. - - - - - ```csharp public override SPMobileBaseFieldControl FieldRenderingMobileControl ``` This property replaces the obsolete **FieldRenderingMobileControl**. - - - The other properties are standard overrides of inherited properties that were in SharePoint 2010. The specific information for this class is in the following table. - - - - |**Property**|**The override...**| |:-----|:-----| |FieldValueType
|Returns **typeof(SPFieldGeolocationValue)**.
| @@ -996,21 +531,14 @@ The other properties are standard overrides of inherited properties that were in Represents a location on the globe defined by longitude, latitude, and possibly altitude too. - - - ```csharp public class SPFieldGeolocationValue : SPFieldGeographyValue ``` - #### Constructors (overloaded) Initializes a new instance of the **SPFieldGeolocationValue** class. - - - ```csharp public SPFieldGeolocationValue() public SPFieldGeolocationValue(string fieldValue) @@ -1020,202 +548,105 @@ public SPFieldGeolocationValue(double latitude, double longitude, double altitud ``` **Parameters** - - - - - _fieldValue_ is a string in one of the following Well-Known Text (WKT) formats: - - "Point( _longitude_ _latitude_)", where _longitude_ and _latitude_ are strings of one or more numerals, optionally including one period (which is interpreted as a decimal point) and optionally beginning with a hyphen (which is interpreted as a negative sign). - - - "Point( _longitude_ _latitude_ _altitude_ _measure_)", where _longitude_, _latitude_, _altitude_, and _measure_ are strings of one or more numerals, optionally including one period (which is interpreted as a decimal point) and optionally beginning with a hyphen (which is interpreted as a negative sign). - - - _latitude_ is the latitude and must be between -90.0 and 90.0. - - - _longitude_ is the longitude and must be between -180.0 and 180.0. - - - _altitude_ is the altitude. - - - _measure_ is an alternate designation of the point. See the **Measure** property later in this section for more information. - #### Methods **ToString** - - - This override returns one of the following, depending on whether the **Altitude** or **Measure** properties have been assigned a non-null value. +- If neither Altitude nor Measure have been assigned a non-null value: - - - -- If neither Altitude nor Measure have been assigned a non-null value: - - "Point( _longitude_ _latitude_)", where _longitude_ and _latitude_ are strings of one or more numerals, optionally including one period (which is interpreted as a decimal point) and optionally beginning with a hyphen (which is interpreted as a negative sign). - + "Point( _longitude_ _latitude_)", where _longitude_ and _latitude_ are strings of one or more numerals, optionally including one period (which is interpreted as a decimal point) and optionally beginning with a hyphen (which is interpreted as a negative sign). - Otherwise (at least one of **Altitude** or **Measure** have been assigned a non-null value): "Point(longitude latitude altitude measure)", where _longitude_, _latitude_, _altitude_, and _measure_ are strings of one or more numerals, optionally including one period (which is interpreted as a decimal point) and optionally beginning with a hyphen (which is interpreted as a negative sign). If either **Altitude** or **Measure** has not been assigned a non-null value, it is reported as "0" in the value of the **WellKnownText** property. The converse does not hold: if either **Altitude** or **Measure** is reported as 0, that might be because it was never assigned a non-null value, but it might be because it was assigned 0. - - - - ```csharp public override string ToString() ``` **ToWellKnownText** - - - Wraps **ToString**. - - - - - ```csharp public string ToWellKnownText() ``` - #### Properties **Altitude** - - Gets or sets the altitude of the location. Use of this property is optional and the assumed unit-of-measure (for example, meters) and zero-point (for example, sea level or center-of-the-earth) is user-defined. - - - - - - ```csharp public double Altitude ``` **Latitude** - - Gets or sets the latitude of the location. - - - - - ```csharp public double Latitude ``` - The value must be between -90.0 and 90.0. - - **Longitude** - - - Gets or sets the longitude of the location. - - - - - ```csharp public double Longitude ``` +The value must be between -180.0 and 180.0. -The value must be between -180.0 and 180.0.. - - - - **Measure** - - +**Measure** Gets or sets a user-defined alternate designation of the location point. For example, if the point is along a highway with milestone markers, this property could be used to hold the number of the milestone that is nearest to the point. If the point is in a public camping area with numbered campsites, this property could be used to hold the number of the nearest campsite. The semantics of the property are entirely user-determined and its use is optional. - - - - ```csharp public double Measure ``` - ### SPFieldType enum - A new value has been added to this enum: - - - ```csharp Geolocation ``` - ### SPPhoneNotificationContent class A base class for classes that represent the content of a phone notification. Derived classes must declare one or more fields or properties to hold the content and must implement the **PreparePayload** method to transform the content into a byte array. - - - ```csharp public abstract class SPPhoneNotificationContent ``` - #### Methods **PreparePayload** - - When implemented in a derived class, transforms the content into a Byte array that is sent over the wire to the notification service. There is no default implementation so a derived class must implement this method. - - - - - ```csharp protected internal abstract byte[] PreparePayload(); ``` - #### Properties **NotificationType** (read-only) - - Gets the type of notification (for example, tile or toast) for which the content is intended. - - - - - ```csharp public SPPhoneNotificationType NotificationType @@ -1223,54 +654,29 @@ public SPPhoneNotificationType NotificationType For information about the **SPPhoneNotificationType**, see later in this document. - - **SubscriberType** (read-only) - - Gets the type of the subscriber's device, for example, a Windows Phone. - - - - - ```csharp public SPPhoneNotificationSubscriberType SubscriberType ``` - For information about the **SPPhoneNotificationSubscriberType**, see later in this document. - - - ### SPPhoneNotificationResponse class Represents the outcome of an attempt to send a notification. - - - ```csharp public class SPPhoneNotificationResponse ``` - #### Methods **Create** - - - Creates an **SPPhoneNotificationResponse** object. - - - - - ```csharp public static SPPhoneNotificationResponse Create(SPPhoneNotificationSubscriberType subscriberType, @@ -1279,36 +685,18 @@ SPPhoneNotificationType notificationType, HttpWebResponse response) **Parameters** - - - - _subscriberType_ is the device, such as Windows Phone 7.5. - - - _notificationType_ is the type of notification, such as toast or tile. - - - _response_ is the HTTP response object that was generated by the server. - For more information about **SPPhoneNotificationSubscriberType** and **SPPhoneNotificationType**, see later in this document. - - - #### Properties **NotificationType** (read-only) - - Gets the type of notification (for example, toast or tile). - - - - - ```csharp public SPPhoneNotificationType NotificationType @@ -1316,345 +704,167 @@ public SPPhoneNotificationType NotificationType For information about the SPPhoneNotificationType, see later in this document. - - **ServiceToken** (read-only) - - - Gets the token of the notification service that was used in the notification. - - - - - ```csharp public string ServiceToken ``` **StatusCode** (read-only) - - - Gets the HTTP status code. A string version of a **HttpStatusCode** value. - - - - - ```csharp public string StatusCode ``` **SubscriberType** - - - Gets or sets the type of device to which the notification was sent. - - - - - ```csharp public SPPhoneNotificationSubscriberType SubscriberType ``` For information about the **SPPhoneNotificationSubscriberType**, see later in this document. - - - - **TimeStamp** (read-only) - - - +**TimeStamp** (read-only) The UTC time of the notification. - - - - - ```csharp public DateTime Timestamp ``` - ### SPPhoneNotificationSubscriber class - A base class for classes that represent a subscriber to notifications issued by a server-side SharePoint application. - - - ```csharp public abstract class SPPhoneNotificationSubscriber ``` - #### Methods - Notify - - - Sends the specified notification content to the subscriber with error checking. - - - - - ```csharp public SPPhoneNotificationResponse Notify(SPPhoneNotificationContent notificationContent) ``` **Parameters** - - - _notificationContent_ is information about the event that triggered the notification. - - - This method cannot be overridden. It wraps the abstract **NotifyInternal** method and ensures that certain error checking is done when **NotifyInternal** is called. - - - For more information about the **SPPhoneNotificationContent** and **SPPhoneNotificationResponse** classes, see earlier in this document. - - **NotifyInternal** - - - When overridden in a derived class, sends the specified notification content to the subscriber. - - - - - ```csharp protected abstract SPPhoneNotificationResponse NotifyInternal(SPPhoneNotificationContent notificationContent); ``` **Parameters** - - - _notificationContent_ is information about the event that triggered the notification. - - For more information about the **SPPhoneNotificationContent** and **SPPhoneNotificationResponse** classes, see earlier in this document. - - **ToString** - - - Returns selected properties of the object as a string. - - - - - ```csharp public override string ToString() ``` The default implementation includes the **ParentWeb**, **ApplicationTag**, and **DeviceAppInstanceId** properties. - - Update - - Saves a (possibly changed) **SPPhoneNotificationSubscriber** object to the website's Subscriber Store. - - - - - ```csharp public void Update() ``` **ValidateSubscriberProperties** - - - When implemented in a derived class, validates selected properties of the object. - - - - - ```csharp protected abstract void ValidateSubscriberProperties(); ``` - #### Properties **CustomArgs** - - Gets or sets a custom arguments string which represents the state of the notifications subscription. This string could be used by the application logic to differentiate between its notification subscribers for different kinds of notifications. - - - - - ```csharp public string CustomArgs ``` **DeviceAppInstanceId** (read-only) - - - Gets an ID for the specific instance of the application on the phone or other mobile device. - - - - - ```csharp public Guid DeviceAppInstanceId ``` **LastModifiedTimeStamp** (read-only) - - - Gets the date and time when the subscriber was last modified. - - - - - ```csharp public DateTime LastModifiedTimeStamp ``` **RegistrationTimeStamp** (read-only) - - - Gets the date and time when the subscriber registered for notifications. - - - - - -```csharp -public DateTime RegistrationTimeStamp -``` +```csharp +public DateTime RegistrationTimeStamp +``` **ServiceToken** - - - Gets or sets delivery channel information that is needed by a notification service, such as channel URI. - - - - - ```csharp public string ServiceToken ``` **SubscriberType** (read-only) - - - Gets the type of the device, such as Windows Phone 7. - - - - - ```csharp public SPPhoneNotificationSubscriberType SubscriberType ``` For information about the **SPPhoneNotificationSubscriberType** class, see later in this document. - - **User** (read-only) - - - Gets the user who registered for notifications. - - - - - ```csharp public SPUser User ``` - ### SPPhoneNotificationSubscriberCollection class A collection of notification subscribers. The collection object takes **Int32** indexers. - - - ```csharp public sealed class SPPhoneNotificationSubscriberCollection : SPBaseCollection ``` - #### Properties **Count** - - Gets the number of items in the collection. - - - - - ```csharp public override int Count ``` - ### SPPhoneNotificationSubscriberType enum Specifies a type of device that can receive notifications. - - - - |**Notification**|**Device**| |:-----|:-----| ||| @@ -1676,64 +886,28 @@ Specifies the type of notification. The following members have been added to this class. - - - #### Methods **DoesPhoneNotificationSubscriberExist** - - - Gets a value that indicates whether the current user is a subscriber for the specified instance of the specified app. - - - - - ```csharp public bool DoesPhoneNotificationSubscriberExist(Guid deviceAppInstanceId) ``` **GetPhoneNotificationSubscriber** - - - Gets a notification subscriber with the specified application and phone IDs from the website's notification Subscription Store list. - - - - - - ```csharp public SPPhoneNotificationSubscriber GetPhoneNotificationSubscriber(Guid deviceAppInstanceId) ``` **Parameters** - - - _deviceAppInstanceId_ is an ID for the instance of the application on a specific phone or device. - - - For information about the **SPPhoneNotificationSubscriber** class see earlier in this document. - - **GetPhoneNotificationSubscribers** (overloaded) - - - Gets a collection of notification subscribers from the website's notification Subscription Store list, optionally filtering on the ID of the phone applications and possibly also on one of the following: the user or some custom arguments. - - - - - ```csharp public SPPhoneNotificationSubscriberCollection GetPhoneNotificationSubscribers(string customArgs) ``` @@ -1742,11 +916,6 @@ public SPPhoneNotificationSubscriberCollection GetPhoneNotificationSubscribers(s > Client object model name is **GetPhoneNotificationSubscribersByArgs**. - - - - - ```csharp public SPPhoneNotificationSubscriberCollection GetPhoneNotificationSubscribers(string user) @@ -1755,516 +924,222 @@ public SPPhoneNotificationSubscriberCollection GetPhoneNotificationSubscribers(s > [!NOTE] > Client object model name is **GetPhoneNotificationSubscribersByUser**. - - - **Parameters** - - - - - _customArgs_ are additional custom information that some notification-enabled applications may use. - - - _user_ is the user who registered for the notifications. - For information about the **SPPhoneNotificationSubscriberCollection** class see earlier in this document. - - **RegisterPhoneNotificationSubscriber** - - - Registers a phone app on a phone to receive notifications. - - - - - ```csharp public SPPhoneNotificationSubscriber RegisterPhoneNotificationSubscriber(SPPhoneNotificationSubscriberType subscriberType, Guid deviceAppInstanceId, string serviceToken) ``` **Parameters** - - - - - _subscriberType_ is the device type, such as Windows Phone 7. - - - _deviceAppInstanceId_ is an ID for the instance of the app on a specific phone or device. - - - _serviceToken_ is the token that is used by the notification service that sends notifications to the subscriber. - - For information about **SPPhoneNotificationSubscriberType**, see earlier in this document. - - **UnregisterPhoneNotificationSubscriber** - - - Unregisters a phone app on a phone from receiving notifications. - - - - - ```csharp public void UnregisterPhoneNotificationSubscriber(Guid deviceAppInstanceId) ``` **Parameters** - - - _deviceAppInstanceId_ is an ID for the instance of the app on a specific phone or device. - - - - #### Properties - **PhoneNotificationSubscribers** (read-only) - - - Gets a collection of all the phone notification subscribers in the website's Subscriber Store. - - - - - ```csharp public SPPhoneNotificationSubscriberCollection PhoneNotificationSubscribers ``` For information about the **SPPhoneNotificationSubscriberCollection** class, see earlier in this document. - - - ### WP7NotificationTileContent class - Represents the content of a tile notification. - - - ```csharp public sealed class WP7NotificationTileContent : SPPhoneNotificationContent ``` - #### Constructors - Initializes a new instance of the WP7NotificationTileContent class. - - - - ```csharp public WP7NotificationTileContent() ``` - #### Methods **PreparePayload** - - - Transforms the content into a **Byte** array that is sent over the wire to the notification service. - - - - - ```csharp protected internal override byte[] PreparePayload(); ``` - #### Properties - **Count** - - - Gets or sets the count of the notification. Must be from -1 to 99 inclusive. - - - - - ```csharp public int Count ``` - Setting the property to -1 will not change the count over the tile. - - **Title** - - - Gets or sets the title of the tile notification. - - - - - - ```csharp public string Title ``` **BackgroundImagePath** - - - Gets or sets the path to the tile's background image. - - - - - - ```csharp public string BackgroundImagePath ``` **BackBackgroundImagePath** - - - Gets or sets the background image of the back side of a flipping tile. - - - - - - ```csharp public string BackBackgroundImagePath ``` **BackContent** - - - Gets or sets the content of the back side of a flipping tile. - - - - - - ```csharp public string BackContent ``` **BackTitle** - - - Gets or sets of the title that appears on the back side of a flipping tile. - - - - - - ```csharp public string BackTitle ``` **TileId** - - - Gets or sets the ID of the tile. - - - - - ```csharp public string TileId ``` - ### WP7NotificationToastContent class Represents the content of a toast notification. - - - ```csharp public sealed class WP7NotificationToastContent : SPPhoneNotificationContent ``` - - #### Constructors - Initializes a new instance of the WP7NotificationToastContent class. - - - - ```csharp public WP7NotificationToastContent() ``` - - #### Methods **PreparePayload** - - - Transforms the content into a **Byte** array that is sent over the wire to the notification service. - - - - - - ```csharp protected internal override byte[] PreparePayload(); ``` - #### Properties - **Message** - - - Gets or sets the message of the toast notification. - - - - - - ```csharp public string Message ``` - **Title** - - - Gets or sets the title of the toast notification. - - - - - - ```csharp public string Title ``` **Param** - - - Gets or sets custom settings data that is passed to the receiving application if the user responds to the toast notification. - - - - - ```csharp public string Param ``` - This property can be used to pass information to the receiving application such as a URL or a set of name-value pairs. - - - ### WP7NotificationRawContent class Represents the content of a raw notification. - - - - ```csharp public sealed class WP7NotificationRawContent : SPPhoneNotificationContent ``` - #### Constructors - Initializes a new instance of the WP7NotificationRawContent class. - - - ```csharp public WP7NotificationRawContent() ``` - - #### Methods **PreparePayload** - - - Transforms the content into a Byte array that is sent over the wire to the notification service. - - - - - ```csharp protected internal override byte[] PreparePayload(); ``` - #### Properties - **Message** - - - Gets or sets the message of the raw notification. - - - - - - ```csharp public string Message ``` - ### WP7PhoneNotificationResponse class - Represents the outcome of an attempt to send a notification to a Windows Phone 7 subscriber. - - - - ```csharp public WP7PhoneNotificationResponse(SPPhoneNotificationType notificationType, HttpWebResponse response) ``` **Parameters** - - - - - _notificationType_ is the type of notification, such as toast or tile. - - - _response_ is the HTTP response object that was generated by the server. - - For more information about **SPPhoneNotificationType**, see earlier in this document. - - - #### Properties **NotificationStatus** (read-only) - - - Gets the notification status, for example, success or failure. - - - - - ```csharp public string NotificationStatus ``` - **DeviceConnectionStatus** (read-only) - - - Gets the status of the device at the time of the notification. - - - - - ```csharp public string DeviceConnectionStatus ``` **SubscriptionStatus** (read-only) - - - The subscription status of the device at the time of the notification. - - - - - ```csharp public string SubscriptionStatus ``` - **MessageId** (read-only) - - - Gets the ID of the message that was sent in the notification. - - - - - - ``` public string MessageId ``` - - ## See also - - - [Build Windows Phone apps that access SharePoint](build-windows-phone-apps-that-access-sharepoint.md) - - - [How to: Configure and use push notifications in SharePoint apps for Windows Phone](how-to-configure-and-use-push-notifications-in-sharepoint-apps-for-windows.md) - - - [Integrating location and map functionality in SharePoint](integrating-location-and-map-functionality-in-sharepoint.md) - - - [Overview of the SharePoint mobile client authentication object model](overview-of-the-sharepoint-mobile-client-authentication-object-model.md) - - - diff --git a/docs/general-development/search-add-ins-in-sharepoint.md b/docs/general-development/search-add-ins-in-sharepoint.md index 2a89dbdc3..2b105d7e8 100644 --- a/docs/general-development/search-add-ins-in-sharepoint.md +++ b/docs/general-development/search-add-ins-in-sharepoint.md @@ -7,15 +7,21 @@ ms.localizationpriority: medium --- # Search add-ins in SharePoint +> [!IMPORTANT] +> The SharePoint Add-in model is deprecated for SharePoint Online and is no longer recommended for new development. +> Microsoft recommends using SharePoint Framework (SPFx) and Microsoft Graph APIs for modern SharePoint extensibility solutions. +> +> Existing SharePoint Add-ins continue to be supported in SharePoint Server environments. + Learn about search SharePoint Add-ins and how you can create your own search add-ins. The add-ins you create can be added to the SharePoint add-ins catalog so that they can be used in both on-premises deployment and Office 365. Search add-ins only work with data that is stored in the search index and not with the original source documents. -SharePoint Add-ins are self-contained pieces of functionality that extend the capabilities of a SharePoint website. These add-ins solve specific business and end-user needs by integrating the best of the web and SharePoint. An add-in can contain various SharePoint elements like Lists, Remote Event Receivers, Content Types, Workflows, Workflow Custom Activities, Site Columns, Modules, Menu Item Custom Actions, Client web parts, and Search Configurations. For more information, see [SharePoint Add-ins](https://msdn.microsoft.com/library/cd1eda9e-8e54-4223-93a9-a6ea0d18df70%28Office.15%29.aspx). +SharePoint Add-ins are self-contained pieces of functionality that extend the capabilities of a SharePoint website. These add-ins solve specific business and end-user needs by integrating the best of the web and SharePoint. An add-in can contain various SharePoint elements like Lists, Remote Event Receivers, Content Types, Workflows, Workflow Custom Activities, Site Columns, Modules, Menu Item Custom Actions, Client web parts, and Search Configurations. For more information, see [SharePoint Add-ins](/sharepoint/dev/sp-add-ins/sharepoint-add-ins). -A search add-in is an SharePoint Add-in that uses search functionality. In a search add-in, you can use the SharePoint Search API to locate content. Depending on the type of permissions set up in your [add-in manifest](https://msdn.microsoft.com/library/7cd5850f-cbf3-48d2-bcb7-59b8f4ed0e63%28Office.15%29.aspx), you can search either inside or outside the contents of the add-in. In addition, you can also use a search add-in to distribute search configurations from one SharePoint installation to another. -The core design of a search add-in depends on the deployment method that you choose. The following section summarizes the available options and their benefits. For more information, see [Choose patterns for developing and hosting your SharePoint Add-in](https://msdn.microsoft.com/library/05ce5435-0a03-4ddc-976b-c33b08d03457%28Office.15%29.aspx) +A search add-in is a SharePoint Add-in that uses search functionality. In a search add-in, you can use the SharePoint Search API to locate content. Depending on the type of permissions set up in your [add-in manifest](/sharepoint/dev/sp-add-ins/explore-the-app-manifest-structure-and-the-package-of-a-sharepoint-add-in), you can search either inside or outside the contents of the add-in. In addition, you can also use a search add-in to distribute search configurations from one SharePoint installation to another. +The core design of a search add-in depends on the deployment method that you choose. The following section summarizes the available options and their benefits. For more information, see [Choose patterns for developing and hosting your SharePoint Add-in](/sharepoint/dev/sp-add-ins/choose-patterns-for-developing-and-hosting-your-sharepoint-add-in) @@ -39,19 +45,15 @@ There are two ways to deploy your search add-in: ## Search add-in development environment -To create a search add-in, use following environment: - - - +> [!NOTE] +> SharePoint Add-ins are a legacy development model. For new development, use SharePoint Framework (SPFx). -- Microsoft Visual Studio 2012 or Microsoft Visual Studio 2013 or Visual Studio 2015 - - -With Visual Studio 2013 and later, you can publish your search add-ins to both on-premises or in Office 365. For more information about the development environments and how to use them to create search add-ins, see [Set up a general development environment for SharePoint](set-up-a-general-development-environment-for-sharepoint.md). - - - +To create a search add-in, use following environment: +- Microsoft Visual Studio Code + +With Visual Studio Code and later, you can publish your search add-ins to both on-premises or in Office 365. For more information about the development environments and how to use them to create search add-ins, see [Set up a general development environment for SharePoint](set-up-a-general-development-environment-for-sharepoint.md). + ## APIs for search add-ins @@ -62,6 +64,8 @@ You can use the wide range of search-related APIs that SharePoint offers for sea **SharePoint APIs for Search add-ins** +> [!NOTE] +> Silverlight-based APIs are deprecated and no longer supported. |**API name**|**Class library**| |:-----|:-----| @@ -73,21 +77,9 @@ You can use the wide range of search-related APIs that SharePoint offers for sea ### Code examples -Here are some code examples using the different APIs. Each code example sends a simple Search query that contains the keyword "SharePoint" to the Search service application (SSA). - - - +Here are some code examples using the different APIs. Each code example sends a simple Search query that contains the keyword "SharePoint" to the Search service application (SSA). **Client-side Object Model (CSOM)** - - - - - - - - - ```csharp using (ClientContext clientContext = new ClientContext("http://localhost")) @@ -103,15 +95,6 @@ using (ClientContext clientContext = new ClientContext("http://localhost")) **JavaScript Object Model (JSOM)** - - - - - - - - - ``` var keywordQuery = new @@ -123,19 +106,8 @@ context.executeQueryAsync(onQuerySuccess, onQueryFail); ``` **REST** - - - - - - - + HTTP GET request - - - - - ```HTML @@ -143,11 +115,6 @@ http://mylocalhost/_api/search/query?querytext='SharePoint' ``` HTTP POST request - - - - - ```HTML { @@ -155,62 +122,26 @@ HTTP POST request 'Querytext' : 'SharePoint' } ``` - - ## Search add-in permissions Search add-ins send query requests to the Search service application (SSA), and the add-ins require different types of permissions to function correctly. You can configure these permissions via the add-in manifest file, which is a part of each SharePoint add-in. You can modify the add-in manifest file directly with a text editor, or you can modify it with Visual Studio or Napa, as shown in the following figures. - - - **Figure 1: Setting up permissions for search add-ins in Visual Studio 2015** - - - - - - - ![Search app permission configuration with VS](../images/SP15_search_apps_permission_Visual_Studio.PNG) - - - - - - - - - - **Figure 2: Setting up permissions for search add-ins in "Napa" Office 365 Development Tools** - - - - - - - + ![Search app permission configuration through Napa](../images/SP15_search_app_permission_Napa.gif) - - An SharePoint Add-in has its own identity and is associated with a security principal, called an add-in principal. Like users and groups, an add-in principal has certain permissions and rights. The add-in principal has full control rights to the add-in web, so it only needs to request permissions to SharePoint resources in the host web or other locations outside the add-in web, such as site collections. Unlike other SharePoint Add-ins, a search add-in requires only user-level permissions, known as **QueryAsUserIgnoreAppPrincipal**. This permission lets you query the search add-in based on the user's permissions. This means that search results will be returned based on the user's ACLs. - - - ### Request permissions in the add-in manifest file The add-in manifest file is in XML format and can be edited directly. To get permissions, you write a request, as shown in the following example: - - - ```XML @@ -218,37 +149,14 @@ The add-in manifest file is in XML format and can be edited directly. To get per ``` - - ## See also - -- [SharePoint Add-ins](https://msdn.microsoft.com/library/cd1eda9e-8e54-4223-93a9-a6ea0d18df70%28Office.15%29.aspx) - - -- [Choose patterns for developing and hosting your SharePoint Add-in](https://msdn.microsoft.com/library/05ce5435-0a03-4ddc-976b-c33b08d03457%28Office.15%29.aspx) - - -- [Add-in permissions in SharePoint](https://msdn.microsoft.com/library/5f7a8440-3c09-4cf8-83ec-c236bfa2d6c4%28Office.15%29.aspx) - - -- [Add-in authorization policy types in SharePoint](https://msdn.microsoft.com/library/124879c7-a746-4c10-96a7-da76ad5327f0%28Office.15%29.aspx) - - -- [Important aspects of the SharePoint Add-in architecture and development landscape](https://msdn.microsoft.com/library/ae96572b-8f06-4fd3-854f-fc312f7f2d88%28Office.15%29.aspx) - - -- [Explore the app manifest structure and the package of a SharePoint Add-in](https://msdn.microsoft.com/library/7cd5850f-cbf3-48d2-bcb7-59b8f4ed0e63%28Office.15%29.aspx) - - -- [Add search capabilities to your add-ins for SharePoint](https://blogs.msdn.com/b/officeapps/archive/2013/05/30/add-search-capabilities-to-your-apps-for-sharepoint.aspx) - - +- [SharePoint Add-ins](/sharepoint/dev/sp-add-ins/sharepoint-add-ins) +- [Choose patterns for developing and hosting your SharePoint Add-in](/sharepoint/dev/sp-add-ins/choose-patterns-for-developing-and-hosting-your-sharepoint-add-in) +- [Add-in permissions in SharePoint](/sharepoint/dev/sp-add-ins/add-in-permissions-in-sharepoint) +- [Add-in authorization policy types in SharePoint](/sharepoint/dev/sp-add-ins/add-in-authorization-policy-types-in-sharepoint) +- [Important aspects of the SharePoint Add-in architecture and development landscape](/sharepoint/dev/sp-add-ins/important-aspects-of-the-sharepoint-add-in-architecture-and-development-landscap) +- [Explore the app manifest structure and the package of a SharePoint Add-in](/sharepoint/dev/sp-add-ins/explore-the-app-manifest-structure-and-the-package-of-a-sharepoint-add-in) - [Exporting and importing search configuration settings in SharePoint](exporting-and-importing-search-configuration-settings-in-sharepoint.md) - - - [Export and import customized search configuration settings in SharePoint (TechNet)](https://technet.microsoft.com/library/jj871675.aspx) - - -