PromoInfoApi.cs

using Microsoft.CommerceServer.Catalog;
using Microsoft.CommerceServer.Runtime.Profiles;

namespace Enticify.CommerceServer.Tests.Scenarios
{
    public class PromoInfoSourceApi
    {
        public void GetPromoInfoForProductAndDoSomething(Product csProduct, Profile csUserProfile)
        {
            var promotionQueryService = new PromotionQueryService();

            //AC: this implies that AvailableToUser is optional - is that correct?
            var promosTargetingProductQuery = new PromotionsTargetingProductQuery(csProduct)
                                        {
                                            AvailableToUser = csUserProfile,
                                        };

            ProductPromotionResults productPromotionResults = promotionQueryService.GetPromotions(promosTargetingProductQuery);
            //AC: if AvailableToUser is optional, you could also have an override that takes just a csProduct, which saves creating a PromotionsTargetingProductQuery
            //AC: unless of course there is more than one type of query that has a product as its principal object.

            if (!productPromotionResults.HasPromotionsTargetingProduct)
                return;

            //Do something cool with the data.
            //AC: Now I've put my mind back in CS-land, this makes more sense, but is still a little more ambiguous...
            //AC: Does WhereConditionOnly only return products that are conditions, but not awards? It sounds like it should
            //AC: If that is the case, how does one get products that are conditions, regardless if they were also awards? Is there a .WhereCondition?
            //AC: I've looked through your previous versions of your gist, and think that TargetedAsCondition is a little clearer
            //AC: Have you also considered productPromotionResults.findWhere(TargetingScope.Condition | TargetingScope.Award) (with a TargetingScope.ConditionAndAward option too) - I'm sure this can be LINQ-ified.     
            var conditionInfos = productPromotionResults.WhereConditionOnly;
            var awardInfos = productPromotionResults.WhereAwardOnly;
            var conditionAndAwardInfos = productPromotionResults.WhereConditionAndAward;
        }
    }
}

//AC: if AvailableToUser is optional, you could also have an override that takes just a csProduct, which saves creating a PromotionsTargetingProductQuery
Agreed. I had same thought.

//AC: unless of course there is more than one type of query that has a product as its principal object.
Not that I can think of at the moment (famous last words).

//AC: Does WhereConditionOnly only return products that are conditions, but not awards? It sounds like it should
Yes.

//AC: If that is the case, how does one get products that are conditions, regardless if they were also awards? Is there a .WhereCondition?
The API is not getting products, it is getting promotion information. Where ConditionOnly returns promos that target the provided product as a condition only.

//AC: I've looked through your previous versions of your gist, and think that TargetedAsCondition is a little clearer
I changed that after feedback from someone else :) Will have another thing about it.

//AC: Have you also considered productPromotionResults.findWhere(TargetingScope.Condition | TargetingScope.Award) (with a TargetingScope.ConditionAndAward option too) - I'm sure this can be LINQ-ified.

Considered Linq. In fact, ProductPromotionResults is actually a specialised list implementing IList) so you could do Linq against it. The additional properties like WhereConditionOnly were intended as convenience properties to guided intellisense driven dev (trying to follow the framework guidelines :)

The reason I like TargetAsCondition is that it is consistent with other language, i.e. PromotionsTargetingProductQuery - it strong reinforces the notion that 'Target' refers to both 'Awards' and 'Conditions'

That said, its been a while since I've touched .NET, so if you think that the Where* fits in the guidelines, I say go for it. :-)

Yeah, I think I might change it back. The Where* naming is not the guideline, the guidance I was channeling was "Don't be afraid to use specialized collections." and "Developers like to discover APIs by newing stuff up and looking at properties. Have a simple API they can get more advanced with as they get familiar." Of course, it's always difficult to get the balance. BTW - would be great to catch up on Skype sometime. Would be cool to hear more about your fantastic SF life.. Let me know when you have some time.