Adding criteria

Article
07/23/2010

In Web Services for Microsoft Dynamics GP, you use criteria objects to specify the summary documents that a GetList method will retrieve in a list. To support a GetList operation, add a criteria class for your document type.

To create a criteria class, complete the following steps:

Create a criteria class.

From the Visual Studio Project menu, choose Add Class. Select Class from the List of Templates in the Add New Item window. Enter a name for your class and click Add. Visual Studio adds a class to your namespace and a file to your project.

Your criteria class should follow the standard naming convention. Typically, the criteria name begins with document type name followed by "Criteria".

DocumentType Criteria

The following example shows the name of the criteria class for Leads:

<pre class="checklistscript" IsFakePre="true" xmlns="http://www.w3.org/1999/xhtml">LeadCriteria

The following code sample shows the declaration of the LeadCriteria class.

<pre class="checklistscript" IsFakePre="true" xmlns="http://www.w3.org/1999/xhtml">class LeadCriteria

{

}

Verify the namespace reference.

If your class file does not already include it, add a using statement for the following namespace:

• Microsoft.Dynamics.Common
Mark the class as serializable.

Add the Serializable and DataContract attributes.
```
[Serializable, DataContract]
```

public class LeadCriteria

Inherit from the Criteria class.

The criteria class must inherit from the Microsoft.Dynamics.Common.Criteria class.

The following code sample adds Criteria as the base class for LeadCriteria.
```
public class LeadCriteria : Criteria
```

Add the class data members.

Add a private data member for each queryable data field. Typically, the criteria data members include the same data fields as the summary class. The type of each data member is a Restriction class. For more information about how to use Restrictions, see Restriction reference.

The following code sample shows the data members of the LeadCriteria class. Notice how each restriction object specifies the type of the data field.
```
private LikeRestriction<string> id;
```

private LikeRestriction<string> name; private LikeRestriction<string> salespersonID; private RestrictionOfNullable<bool> qualifiedLead; private LikeRestriction<string> leadSource; private BetweenRestrictionOfNullable<DateTime> modifiedDate;

Add a property for each data member.

Add a property that provides access to each data member. The property allows you to set or retrieve the value of each data member.

Use the DataMember attribute to identify each property as a data member. In addition, set the EmitDefaultValue property to false for all reference types and non-nullable enumeration types.

The following sample code shows the properties of the LeadCriteria class:
```
[DataMember(EmitDefaultValue = false)]
```

public LikeRestriction<string> Id { get{return id;} set{id = value;} } [DataMember(EmitDefaultValue = false)] public LikeRestriction<string> Name { get{return name;} set{name = value;} } [DataMember(EmitDefaultValue = false)] public LikeRestriction<string> SalespersonID { get{return salespersonID;} set{salespersonID = value;} } [DataMember(EmitDefaultValue = false)] public RestrictionOfNullable<bool> QualifiedLead { get{return qualifiedLead;} set{qualifiedLead = value;} } [DataMember(EmitDefaultValue = false)] public LikeRestriction<string> LeadSource { get{return leadSource;} set{leadSource = value;} } [DataMember(EmitDefaultValue = false)] public BetweenRestrictionOfNullable<DateTime> ModifiedDate { get{return modifiedDate;} set{modifiedDate = value;} }

Add a constructor (if required).

If the data members of your criteria class require initial values, use the constructor to set the value of each data member. The LeadCriteria did not require the constructor to complete any initialization.
Override the BuildArrays method.

Add a method that overrides the BuildArrays method of the base class. Use the method to create an array that specifies the name of each column in the database table where the criteria data is stored. Also, create two arrays that specify the name of the properties you added to your criteria class.

The following sample code shows the BuildArrays method of the LeadCriteria class. Notice the following:

• The columns array identifies each column using the Physical Name from the Dexterity dictionary. The DEX_ROW_TS column is included because the Use Row Timestamp option was marked in the table definition.

• The restriction arrays specify the property names from the criteria class. Notice how ModifiedDate is cast to BetweenRestriction<DateTime?>. Resrictions require this type for all datetime values. The "?" indicates that the datetime can accept null as a value.

• The order of the properties in the restriction arrays must match the order of the columns in the columns array. For example, the ID properly must be the first member of the restriction arrays because the LeadID is the first member of the columns array.
```
protected override void BuildArrays()
```

{ columns = new string[] { "LeadID", "LeadName", "SLPRSNID", "QualifiedLead", "LeadSource", "DEX_ROW_TS" };

restrictions = new Restriction[] { Id, Name, SalespersonID,
    QualifiedLead, LeadSource,
    (BetweenRestriction&lt;DateTime?&gt;)ModifiedDate };

convertToUpperCaseRestriction = new Restriction[] { Id, Name,
    SalespersonID, QualifiedLead, LeadSource,
    (BetweenRestriction&lt;DateTime?&gt;)ModifiedDate };

}

Override the GetWhereClause method (if required).

You might find that the values of the criteria class properties do not correspond to the values stored in the data fields of the Dynamics GP database. For example, the database may use values other than "0" and "1" for a boolean field. To adjust for these types of data inconsistencies, you can override the GetWhereClause method of the base class. When you override the GetWhereClause method, you can specify the data values the criteria object uses to query the Dynamics GP database.

For example, the QualifiedLead field is a boolean field but the values stored in Dynamics GP are "1" for false and "2" for true instead of "0" and "1". The following sample code shows how to override the GetWhereClause method so the LeadCriteria class correctly identifies qualified leads.
```
public override string GetWhereClause()
```

{ StringBuilder whereClause = new StringBuilder(base.GetWhereClause());

if (QualifiedLead != null)
{
    if (QualifiedLead.EqualValue == true)
    {
        whereClause.Replace("QualifiedLead = 1", "QualifiedLead = 2");
        whereClause.Replace("QualifiedLead = 0", "QualifiedLead = 1");
    }
    if (QualifiedLead.EqualValue == false)
    {
        // Replace the value of QualifiedLead when the query
        // retrieves records marked as False
        whereClause.Replace("QualifiedLead = 0", "QualifiedLead = 1");
        // Replace the value of QualifiedLead when the query
        // retrieves records that are not marked as True.
        whereClause.Replace("QualifiedLead &lt;&gt; 1",
            "QualifiedLead &lt;&gt; 2");
    }
}
return whereClause.ToString();

}

Save the class.

From the File menu, choose Save.

Share via

Adding criteria

Additional resources