FilterDescriptor Class

Filters are the fundamental way in which the Business Data Catalog captures user (or system) input and plumbs it through to the backend API invocation. FilterDescriptors describe where in a complex series of parameters, a filter value should be inserted. This is accomplished by 'tagging' the TypeDescriptors representing complex parameters of a Method definition to flag where the insertion should happen. It is important to note that the backend must supply the functionality for filtering; the FilterDescriptors merely form a mechanism to surface this to the end user. FilterDescriptor objects are owned (contained) inside Method objects. They are subsequently referred by TypeDescriptor objects.

Inheritance Hierarchy

System.Object
  Microsoft.Office.Server.ApplicationRegistry.Administration.MetadataObject
    Microsoft.Office.Server.ApplicationRegistry.Administration.AccessControlledMetadataObject
      Microsoft.Office.Server.ApplicationRegistry.Administration.FilterDescriptor

Namespace:  Microsoft.Office.Server.ApplicationRegistry.Administration
Assembly:  Microsoft.SharePoint.Portal (in Microsoft.SharePoint.Portal.dll)

Syntax

'Declaration
<SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel := True)> _
<SharePointPermissionAttribute(SecurityAction.Demand, ObjectModel := True)> _
Public Class FilterDescriptor _
    Inherits AccessControlledMetadataObject

'Usage
Dim instance As FilterDescriptor

[SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
[SharePointPermissionAttribute(SecurityAction.Demand, ObjectModel = true)]
public class FilterDescriptor : AccessControlledMetadataObject

Remarks

Users may want to retrieve the instances of an entity that match some criteria. For example, a user may want to display the customers whose names begin with "A" or the orders made by a certain customer. The API used to retrieve customers requires that this user input be passed in as the third String parameter in the invocation. The metadata author will create a FilterDescriptor of a Wildcard Type, and then tag the third parameter's root TypeDescriptor with this newly created FilterDescriptor. Many such FilterDescriptors may be associated with a single Method (API).Users then choose the filter they want at run time, specify a value for it, and the Business Data Catalog passes that filter's value to the back-end method, inserting it into the exact location where the backend expects it, which causes it to then returns only the rows the user wants to see.

Note

FilterDescriptor is a metadata object whereas filters are run-time objects. FilterDescriptor objects describe the filters available on a method.

Filtering Patterns

Line-of-business (LOB) systems provide various filtering mechanisms. The Business Data Catalog abstracts common patterns so it can provide users with the same filtering semantics, regardless of the data source. The Business Data Catalog supports the following filters and filtering patterns:

• Wildcard filter   Limits the instances returned to those where field like value, where value may contain the asterisk (*) wildcard character. Users can use this filter type to present more user-friendly filters such as "starts with" and "contains."

• Comparison filter   Limits the instances returned to those where the condition is met. SQL supports it with the WHERE clause.

• Limit filter   Limits the number of instances returned to n. SQL supports it with the SELECT TOP clause. By using a Limit filter, you can prevent long waits, time outs and also prevent users from issuing bad queries that request large amounts of data.

• UserContext   Limits the instances by the current user's context. This filter tells the Business Data Catalog to append the current Microsoft Windows user's domain\username to the method call.

• Username   Limits the instances by a single sign-on (SSO) user name. This filter tells the Business Data Catalog to pass the user name from SSO as part of a parameter to the method call.

• Password   Works with the Username filter. This filter tells the Business Data Catalog to pass the password from SSO as part of a parameter to the method call.

  Note

  The back-end method definition should support the filters. Only then can you, in a context-sensitive manner, use filters to reflect in the front-end application the functionality that is available in the back end. The metadata simply declares which filters a method supports.

• UserProfile    A simple filter type you can specify in the FilterDescriptor definition. To use this filter, declare a filter of the type "UserProfile" and add a System.String property with the name "UserProfilePropertyName", whose value is the name of a User Profile property. The Business Data Catalog will look up the current user's profile, read the value of the property with this name, and plumb that through to the back-end invocation.

• SSOTicket   Tells the Business Data Catalog to pass the SSO ticket from SSO as part of a parameter to the method call.

• LastIdSeen   Enables chunking for IDEnumerator enumeration members. For Web services and other non-streaming back-end applications, you should use the LastIdSeen filter in your IDEnumerator member to improve performance, as shown in the following example:

  SELECT TOP 100 Id FROM Customers WHERE Id>=@LastIdSeen
  ORDER BY Id
  

User filters such as Wildcard and Range declare which inputs users can override, and system filters such as UserContext and UserProfile allow the Business Data Catalog to securely set values such as user token.

Important

If a metadata author creates bad metadata that takes a user name as a user-controllable filter and returns sensitive personal data, a user may see another user's data. To avoid this, use UserContextFilter to pass in the user name to the method call.

Clients query the metadata repository to determine which filters the system supports and render their user interfaces accordingly.

Following are the properties that the FilterDescriptor object accepts for both database and Web service systems.

Property	Type	Required	Default Value	Limits/Accepted Values	Comments
UsedForDisambiguation	System.Boolean	No	false	true false	If true, this filter is used in the business data picker to generate the list of possible matches.
CaseSensitive	System.Boolean	No	false	true false	If true, the Business Data Web Parts and Business Data picker tell the user this filter is case sensitive.
IsDefault	System.Boolean	No	false	true false	If true, this filter is selected by default in the Business Data picker.

Examples

The following code example shows you how to create a method, complete with method instances, filter descriptors, default values, and TypeDescriptors for the ProductModel entity in the AdventureWorks2000 database.

Prerequisites

• Ensure a Shared Service Provider is already created.

• Create an LobSystem and set connection parameters as shown in How to: Create an LobSystem Using the Administration Object Model.

• Create the ProductModel entity as shown in How to: Create an Entity Using the Administration Object Model

• Replace the constant value EnterYourSSPNameHere in the code with the name of your Shared Resource Provider.

Project References

Add the following Project References in your console application code project before running this sample:

• Microsoft.SharePoint

• Microsoft.SharePoint.Portal

• Microsoft.Office.Server

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.Office.Server.ApplicationRegistry.Administration;
using Microsoft.Office.Server.ApplicationRegistry.Infrastructure;
using WSSAdmin = Microsoft.SharePoint.Administration;
using OSSAdmin = Microsoft.Office.Server.Administration;

namespace Microsoft.SDK.SharePointServer.Samples
{
    class GetStartedAndCreateSystem
    {
        const string yourSSPName ="EnterYourSSPNameHere";

        static void Main(string[] args)
        {
            SetupBDC();
            CreateFinderMethod();
            Console.WriteLine("Press any key to exit...");
            Console.Read();
        }
        static void SetupBDC()
        {
            SqlSessionProvider.Instance().SetSharedResourceProviderToUse(yourSSPName);
        }
        static void CreateFinderMethod()
        {

            LobSystemInstance mySysInstance = null;
            LobSystemInstanceCollection sysInsCollection = ApplicationRegistry.Instance.GetLobSystemInstancesLikeName("AdventureWorksSampleFromCode");
            foreach (LobSystemInstance sysInstance in sysInsCollection)
            {
                if (sysInstance.Name == "AdventureWorksSampleFromCode")
                {
                    mySysInstance = sysInstance;
                    break;
                }
            }
            EntityCollection entityColl = mySysInstance.LobSystem.Entities;
            foreach (Entity entity in entityColl)
            {
                if (entity.Name == "ProductModel")
                {
                    Method meth = entity.Methods.Create("GetProductModels", true, true);
                    meth.Properties.Add("RdbCommandText", "SELECT ProductModelID, Name, CatalogDescription FROM ProductModel WHERE Name LIKE @Name");
                    meth.Properties.Add("RdbCommandType", System.Data.CommandType.Text);
                    FilterDescriptor fd = meth.FilterDescriptors.Create("Name", true, "Microsoft.Office.Server.ApplicationRegistry.Runtime.WildcardFilter");
                    Parameter p1 = meth.Parameters.Create("@Name", true, Microsoft.Office.Server.ApplicationRegistry.MetadataModel.DirectionType.In, "Microsoft.Office.Server.ApplicationRegistry.Infrastructure.DotNetTypeReflector");
                    TypeDescriptor td1 = p1.CreateRootTypeDescriptor("Name", true, "System.String", null, fd, false);
                    Parameter p2 = meth.Parameters.Create("ProductModels", true, Microsoft.Office.Server.ApplicationRegistry.MetadataModel.DirectionType.Return, "Microsoft.Office.Server.ApplicationRegistry.Infrastructure.DotNetTypeReflector");
                    IList<Identifier> ids = new List<Identifier>(entity.Identifiers);
                    Identifier id = ids[0];
                    TypeDescriptor td2 = p2.CreateRootTypeDescriptor("ProductModelDataReader", true, "System.Data.IDataReader, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", null, null, true);
                    TypeDescriptor td21 = td2.ChildTypeDescriptors.Create("ProductModelDataRecord", true, "System.Data.IDataRecord, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", null, null, false);
                    TypeDescriptor td210 = td21.ChildTypeDescriptors.Create("ProductModelID", true, "System.Int32", id, null, false);
                    TypeDescriptor td211 = td21.ChildTypeDescriptors.Create("Name", true, "System.String", null, null, false);
                    TypeDescriptor td212 = td21.ChildTypeDescriptors.Create("CatalogDescription", true, "System.String", null, null, false);
                    MethodInstance methInst1 = meth.MethodInstances.Create("ProductModelFinder", true, td2, Microsoft.Office.Server.ApplicationRegistry.MetadataModel.MethodInstanceType.Finder);
                    MethodInstance methInst2 = meth.MethodInstances.Create("ProductModelSpecificFinder", true, td2, Microsoft.Office.Server.ApplicationRegistry.MetadataModel.MethodInstanceType.SpecificFinder);
                    IList<MethodInstance> methInstCollection = new List<MethodInstance>(entity.MethodInstances);
                    td1.SetDefaultValue(methInstCollection[0].Id, "%");
                    td1.SetDefaultValue(methInstCollection[1].Id, "%");
                    Console.WriteLine("Created the finder method successfully.");
                    break;
                }
            }
        }
    }
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

FilterDescriptor Members

Microsoft.Office.Server.ApplicationRegistry.Administration Namespace