SqlPersonalizationProvider.FindState Method

Note: This method is new in the .NET Framework version 2.0.

Returns a collection containing zero or more PersonalizationStateInfo-derived objects, based on the specified scope and parameters.

Namespace: System.Web.UI.WebControls.WebParts
Assembly: System.Web (in system.web.dll)

public:
virtual PersonalizationStateInfoCollection^ FindState (
	PersonalizationScope scope, 
	PersonalizationStateQuery^ query, 
	int pageIndex, 
	int pageSize, 
	[OutAttribute] int% totalRecords
) override
public PersonalizationStateInfoCollection FindState (
	PersonalizationScope scope, 
	PersonalizationStateQuery query, 
	int pageIndex, 
	int pageSize, 
	/** @attribute OutAttribute() */ /** @ref */ int totalRecords
)
JScript does not support passing value-type arguments by reference.

Parameters

scope

A PersonalizationScope indicating the personalization information to be queried. This value cannot be a null reference (Nothing in Visual Basic).

query

A PersonalizationStateQuery containing a query. This value can be a null reference (Nothing in Visual Basic).

pageIndex

The location where the query starts.

pageSize

The number of records to return.

totalRecords

The total number of records available.

Return Value

A PersonalizationStateInfoCollection containing zero or more PersonalizationStateInfo-derived objects.

Exception typeCondition

ArgumentException

pageIndex is less than zero.

- or -

pageSize is less than or equal to zero.

- or -

The combination of pageIndex and pageSize results in a value greater than MaxValue.

- or -

PathToMatch is non-a null reference (Nothing in Visual Basic) and is an empty string ("") after trimming.

- or -

The length of PathToMatch is greater than 256 characters when the value is non-a null reference (Nothing in Visual Basic).

- or -

UsernameToMatch is non-a null reference (Nothing in Visual Basic) and is an empty string after trimming.

- or -

The length of UsernameToMatch is greater than 256 characters when the value is non-a null reference (Nothing in Visual Basic).

ArgumentOutOfRangeException

The scope specified is not a valid value from the PersonalizationScope enumeration.

The set of returned items is constrained by the pageSize and pageIndex parameters, where pageSize controls the number of records to return and pageIndex controls which records to return. For example, a pageIndex of 0 and a pageSize of 25 would return the first 25 occurrences, while a pageIndex of 1 and a pageSize of 25 would return occurrences 26-50. If you want to fetch all available records, set pageIndex to 0, and pageSize to MaxValue.

The PersonalizationStateInfo-derived objects are returned in alphabetical order sorted by Path and Username, both in ascending order.

This method passes query wildcard characters to the underlying data store. Support for wildcard characters is currently dependent on how each provider handles characters such as an asterisk (*), a percent symbol (%), or an underscore (_).

Normally, for SQL-compliant data stores, you can perform a wildcard search on a partial path with the wildcard character appearing at the beginning, the end, or the middle of the search string text in the PathToMatch property. For example, to find all paths that start with "~/approot", the PathToMatch property would be set to "~/approot%".

Likewise, a wildcard search on a partial user name could have the wildcard character appear at any point in the text string of the UsernameToMatch property. For example, to find all user names that start with "John", the UsernameToMatch parameter would look like "John%".

The following query constraints apply:

  • If only scope is provided, and query is a null reference (Nothing in Visual Basic) or all the properties on query return either a null reference (Nothing in Visual Basic) or default values, then all records matching the indicated scope parameter are returned.

  • If the PathToMatch property is not a null reference (Nothing in Visual Basic), the returned records are also filtered based on paths that match the PathToMatch property value.

  • If the UsernameToMatch property is not a null reference (Nothing in Visual Basic), the returned records are also filtered based on user names that match the UsernameToMatch property value.

  • If the UserInactiveSinceDate property is not equal to MaxValue, then the returned records are also filtered to return only those records associated with inactive users. The comparison includes records where the LastActivityDate property is less than or equal to the UserInactiveSinceDate property.

Note that this method does not validate combinations of query parameters. For example, code can request a set of personalization state records associated with a specific user name in the shared scope. Because user names are not associated with shared information, the returned collection would be empty.

Parameter combinations that have the potential to return a non-empty collection include:

  • Shared scope in combination with PathToMatch.

  • User scope in combination with the values for any or all of the PathToMatch, UsernameToMatch, and UserInactiveSinceDate properties.

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0

Community Additions

ADD
Show: