SharePoint Configuration

The control accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the control, access to these internal properties is provided through the Config method.

SPDocuments Configuration Settings

CheckInType: The type of check-in performed.

This configuration option allows the check-in type to be specified when CheckIn is called. The valid arguments are:


0	Minor CheckIn
1	Major CheckIn
2	Overwrite CheckIn

The UseSOAP configuration option must be "true" for this option's use.

CheckOutToLocal: Whether the file is to be checked out for offline editting.

When this configuration option is set to True, the file checked out by CheckOut will be marked as checked out for offline editting. This option defaults to False.

The UseSOAP configuration option must be "true" for this configuration option's use.

DocComment: Used to set the first comment when adding a document.

If the library to which the document is being added supports versioning, the comment associated with the initial addition may be set by specifying a value for this setting.

DocMetaInfo: Specifies the metadata to be associated with a document when it is added.

This may be set before calling Add to associate metadata with a document. The format expected is "name1;value1;name2;value2" and so on. For example, to specify the title and a custom column value you could do:

SPDocuments1.Config("DocMetaInfo=vti_title;SW|My New Title;MyColumn;New Value");

If you wish to set metadata on an existing document the UpdateItems method of the SPList control may be used.

DocumentAuthor[i]: The author of the document indicated by index i.

When StoreDocumentList is True, this setting returns the author of the document indicated by the index i returned by a call to the List method.

Valid index values are from 0 to DocumentCount - 1.

DocumentCheckedOutBy[i]: The user who has checked out the document indicated by index i.

When StoreDocumentList is True, this setting returns the user who has checked out the document indicated by the index i returned by a call to the List method. If the document is not checked out, this setting will be an empty string.

Valid index values are from 0 to DocumentCount - 1.

DocumentCount: The number of documents returned by a call to List.

When StoreDocumentList is True, this setting returns the number of documents returned by a call to the List method.

DocumentCreated[i]: The date and time the document indicated by index i was created.

When StoreDocumentList is True, this setting returns the date and time the document indicated by the index i was created. The date/time will be formatted as "YYYY-MM-DD hh:mm:ss:".

Valid index values are from 0 to DocumentCount - 1.

DocumentFileName[i]: The filename of the document indicated by index i.

When StoreDocumentList is True, this setting returns the filename of the document indicated by the index i.

Valid index values are from 0 to DocumentCount - 1.

DocumentFileReference[i]: The file reference of the document indicated by index i.

When StoreDocumentList is True, this setting returns the file reference (the path and filename) of the document indicated by the index i.

Valid index values are from 0 to DocumentCount - 1.

DocumentIsFolder[i]: Whether the document indicated by index i is a folder.

When StoreDocumentList is True, this setting returns whether the document indicated by the index i is a folder or not.

Valid index values are from 0 to DocumentCount - 1.

DocumentModified[i]: The date and time the document indicated by index i was last modified.

When StoreDocumentList is True, this setting specifies the date and time the document indicated by the index i was last modified. The date/time will be formatted as "YYYY-MM-DD hh:mm:ss:".

Valid index values are from 0 to DocumentCount - 1.

DocumentSourceControlVersion[i]: The source control version of the document indicated by index i.

When StoreDocumentList is True, this setting returns source control version of the document indicated by the index i.

Valid index values are from 0 to DocumentCount - 1.

DocumentIndex: Selects a document.

When StoreDocumentList is True, this configuration setting may be set to a value between 0 and DocumentCount - 1 in order to select a document. Once set, the following configuration settings will be populated:

DocumentFieldCount: The number of fields for the current document.

This configuration reflects the number of fields in the current document. This is relevant when setting DocumentFieldName and DocumentFieldValue configuration settings.

DocumentFieldName[i]: The name of the field at the specified index.

When queried outside of the Document Event, and StoreDocumentList is True, this setting returns the name of the field at index i for the document specified by DocumentIndex. Within the Document Event, setting the StoreDocumentList configuration is not necessary and this setting will return the value of the field at index i for the current document.

Valid index values are from 0 to DocumentFieldCount - 1.

DocumentFieldValue[i]: The value of the field at the specified index.

When queried outside of the Document Event, and StoreDocumentList is True, this setting returns the value of the field at index i for the document specified by DocumentIndex. Within the Document Event, setting the StoreDocumentList configuration is not necessary and this setting will return the value of the field at index i for the current document.

Valid index values are from 0 to DocumentFieldCount - 1.

IncludedFields: The fields to request when calling List.

This configuration setting accepts a comma separated list of field names that will be requested when calling List. The default value is "LinkFilename,Created Date,Last Modified,Editor,CheckoutUser,owshiddenversion,FSObjType", and the control uses these values to populate the Document Event parameters, as well as their corresponding configuration settings when StoreDocumentList is True. If the default fields are not requested, these values may be empty.

To obtain the values of the requested fields outside of the Document Event, StoreDocumentList must be set to True before calling List. Then, set DocumentIndex, and use the DocumentFieldName and DocumentFieldValue configuration settings to obtain the name value pairs, like so:

int count = Int32.Parse(docs.Config("DocumentCount"));
for (int i = 0; i < count; i++)
{
  docs.Config("DocumentIndex=" + i);
  int fieldCount = Int32.Parse(docs.Config("DocumentFieldCount"));
  for (int j = 0; j < fieldCount; j++)
  {
    Console.WriteLine(docs.Config("DocumentFieldName[" + j + "]"));
    Console.WriteLine(docs.Config("DocumentFieldValue[" + j + "]"));
  }
}

Within the Document Event, setting the StoreDocumentList and DocumentIndex configuration settings is not necessary, and the DocumentFieldName and DocumentFieldValue configuration settings may be queried to obtain the values of the requested fields for the current document.

IncludeFieldsWithViewId: Indicates whether to use the IncludedFields setting when using the ViewId setting.

This configuration setting indicates whether to use IncludedFields when ViewId is set. By default, this setting is false.

IncludeOrderById: Whether to request that results are ordered by Id when listing documents.

When calling List this setting controls whether the results are ordered by Id. If ViewId is set to a view that does not include Id as a column this should be set to False so that the view results are returned correctly. The default value is True.

LastModified: A date in RFC 1123 date format representing the date and time of the last modification to the file.

If this configuration option is set, the server will compare the submitted lastModified value with the stored lastModified value during CheckOut. If the values do not match, the CheckOut fails and an error is returned.

The UseSOAP configuration option must be "true" for this option's use.

PagingId: Used to check for paged results from SharePoint.

This configuration setting can be queried to see if more pages of results are available from SharePoint. If this setting returns a non-empty string, the List* method can be called again to fetch the next page of results. The RowLimit setting should be used to set the page size for paged results.

Query: The query to be used while listing documents.

This configuration setting is used by the List method.

Detailed information about the CAML Query Schema can be found at this URL: http://msdn.microsoft.com/en-us/library/ms467521.aspx

RawEntry: Returns the raw entry for the listing inside.

While in the Document event, this setting will provide the full XML entry for the current document.

ResolveLibraryNames: Controls whether or not library names will automatically be resolved.

Some Document Library names (such as those containing non-ASCII characters) will have an internal name different than their Display Name, and some operations on the Document Library require that the internal name is used rather than the Display Name. When this configuration option is set to "true" the control will automatically attempt to resolve the Display Name to the internal name when needed. The default is false.

RowLimit: Limits the rows returned by ListItems.

This configuration will limit the number of rows returned by a call to ListItems. If this is not specified, the default value is set by SharePoint.

SiteURL: The complete URL for a service.

The control will normally use the URL property to construct the URL for a specific service. This setting overrides the value of this URL.

Scope: Sets the scope for the View used by the List method.

This configuration can be used to set the Scope of the View that the List method uses to retrieve items from the list. Valid input options are:

FilesOnly - Show only the files of the specified list.
Recursive - Show all files of the specified list and all folders in the specified list.
RecursiveAll - Show all files of the list and all subfolders of all folders in the list.

SOAPResponse: The response from the last request.

This configuration setting will contain the entire SOAPResponse, or other HTTP response, that is received from the SharePoint Server.

SOAPRequest: The contents of the request sent to the server.

This setting will provides the full contents of the SOAP packet or other data sent to the server during a transaction.

StoreDocumentList: Whether or not to store the Documents returned by the List method.

When this setting is true the control will store the document details returned by List in memory. When false (default), the document details will only be accessible in the Document event.

Subfolder: The subfolder of the specified document library.

This configuration is used by the control when List is called to limit the file listing to files in the specified Subfolder. When not set, all files in the document library will be listed.

Note: This must contain the path to the folder which will include the document library name.

FormBasedCookies: Holds the security cookies for Form-Based Authentication.

This setting is automatically populated when AuthScheme is set to form based and a method is called. If this setting is populated before calling a method, the control will use the specified cookies.

If the cookies specified in this setting become invalid, set this to an empty string to clear the cookies before re-attempting authentication.

SPOnlineSecurityCookies: Holds the security cookies for SharePoint Online.

This setting is automatically populated when AuthScheme is set to SPOnline and a method is called. If this setting is populated before calling a method the control will use the specified cookies.

If the cookies specified in this setting become invalid, set this to empty string to clear the cookies before re-attempting authentication.

SPOnlineSSO: Whether to use Single Sign On (SSO) with Active Directory Federation Services (ADFS).

This setting may be set to True to use Single Sign On with Active Directory Federation Services (ADFS) to authenticate to SharePoint Online. This is only applicable when AuthScheme is set to SPOnline. URL should be set to the SharePoint Online site URL. For instance:

list.URL = "https://mycrm.sharepoint.com";
list.User = "test@test.com";
list.AuthScheme = SplistAuthSchemes.authSPOnline;
list.Config("SPOnlineSSO=true");
list.Config("FollowRedirects=1");
list.List = "MyCustomList";
list.ListItems();

You may also generate and use SPOnlineSecurityCookies. For instance:

list.URL = "https://mycrm.sharepoint.com";
list.User = "test@test.com";
list.AuthScheme = SplistAuthSchemes.authSPOnline;
list.Config("SPOnlineSSO=true");
list.Config("FollowRedirects=1");
String cookie = list.Config("SPOnlineSecurityCookies");

...

list2.URL = "https://mycrm.sharepoint.com";
list2.Config("HttpCookies=" + cookie);
list2.AuthScheme = SplistAuthSchemes.authNone;
list2.Config("FollowRedirects=1");
list2.List = "MyCustomList";
list2.ListItems();

The default value is False.

SPOnlineSTS: The URL of the online STS.

This setting specifies the URL of the online STS. The default value is "https://login.microsoftonline.com/rst2.srf".

SPOnlineADFSAuthScheme: The HTTP authentication scheme used when working with SSO.

This setting controls the HTTP authentication scheme used when connecting to SharePoint online using SSO. This is only applicable if SPOnlineSSO is set to True. Possible values are:

0 (Basic)
1 (Digest)
2 (Proprietary)
3 (None)
4 (NTLM - Default)
5 (Negotiate/Kerberos)
6 (OAuth)

SSODomain: Specifies the federation domain configured in Office 365.

SSODomain should be set to "OneLogin" when authenticating SharePoint Online via Office 365 through OneLogin Single Sign-On.

UseSOAP: Whether to use SOAP or RPC calls for SharePoint operations.

SharePoint supports two methods for performing actions on the SharePoint server called RPC and SOAP. Setting this configuration option to "true" will cause the component to issue SOAP requests. When set to "false" RPC requests are used. The default is "false". This configuration option is currently only effective for the CheckIn and CheckOut requests.

VersionURL: Used to retrieve a specific past version of a document from SharePoint.

A previous version of the file can be retrieved by specifying this configuration setting prior to calling the Get method. This should be set to a valid version URL, which can be obtained using the ListVersions method.

Note: When this configuration setting is specified, the parameter passed to the Get method is ignored. After the file is retrieved, the VersionURL value is cleared.

ViewID: The GUID of a view to use when listing documents.

This setting may be set to the GUID of a view associated with this document library. When specified the view will be applied when returning results from List. This provides an easy way to determine which fields will be returned.

EncryptionIV: The initialization vector to be used for encryption/decryption.

When encrypting or decrypting a file this may be set this to the initialization vector. Normally the control will derive this value using the value specified in EncryptionPassword, however if a specific value is required it may be set here instead.

This setting accepts a hex encoded value.

EncryptionKey: The key to use during encryption/decryption.

When encrypting or decrypting a file this may be set this to the key. Normally the control will derive this value using the value specified in EncryptionPassword, however if a specific value is required it may be set here instead.

This setting accepts a hex encoded value.

XML Configuration Settings

ParseCustomResponse: Whether to automatically parse the response from the SendCustomRequest() method.

If the SharePoint site uses SOAP for its communication protocol, this configuration option can be set to "true" to automatically parse the SOAP response.

When this configuration option is set to "true" the control will automatically parse the SOAP response from the SharePoint server and the XML configuration options below can be used to navigate the XML structure of the response.

This configuration option should be set to "true" only if the SharePoint site uses the SOAP protocol for communication. This configuration option will not function for the RPC protocol. The default value is "false".

XPath: Provides a way to point to a specific element in the returned XML response.

XPath implements a subset of the XML XPath specification, allowing you to point to specific elements in the XML documents. The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current XPath location. The following are possible values for an element accessor:


'name'	A particular element name
name[i]	The i-th subelement of the current element with the given name
[i]	The i-th subelement of the current element
[last()]	The last subelement of the current element
[last()-i]	The subelement located at the last location minus i in the current element
name[@attrname="attrvalue"]	The subelement containing a particular value for a given attribute (supports single AND double quotes)
..	The parent of the current element

When XPath is set to a valid path, XElement points to the name of the element, with XParent, XNamespace, XPrefix, XChildren, and XText providing other properties of the element. The attributes of the current element are provided in the XAttributes collection . Example (Setting XPath)


Document root	XMLpControl.XPath = "/"
Specific Element	XMLpControl.XPath = "/root/SubElement1/SubElement2/"
i-th Child	XMLpControl.XPath = "/root/SubElement1[i]"

XText: The text of the current element.

The current element is specified in the XPath configuration option.