Prise en charge de l'évaluation des fonctions dans les formules

Aspose.Tasks for .NET API prend en charge l’évaluation des fonctions définies comme formules dans les Extended Attributes d’un projet.
Cela permet aux développeurs d’effectuer des calculs similaires à ceux disponibles dans Microsoft Project, ce qui rend possible l’implémentation de champs dynamiques dépendant d’une logique personnalisée.

L’API offre un support d’évaluation pour les catégories de fonctions suivantes :

• Fonctions mathématiques
• Fonctions générales
• Fonctions de texte
• Fonctions Date/Heure

Cette fonctionnalité est particulièrement utile lorsque vous devez :

• Automatiser les calculs de projet,
• Mettre en œuvre des règles métier personnalisées,
• Assurer la compatibilité des formules entre MS Project et Aspose.Tasks.

Calcul d’expressions mathématiques

Les fonctions mathématiques suivantes sont prises en charge :

1. Abs( number )
2. Atn( number )
3. Cos( number )
4. Exp( number )
5. Fix( number )
6. Int( number )
7. Log( number )
8. Rnd( number )
9. Sgn( number )
10. Sin( number )
11. Sqr( number )
12. Tan( number )

static void EvaluateSine()
{
    Project project = CreateTestProjectWithCustomField();
    
    // Set formula Sin(pi/2)
    project.ExtendedAttributes[0].Formula = "Sin(3.1415926/2)";

    // Print Calculated value
    Task task = project.RootTask.Children.GetById(1);
    Console.WriteLine("Sin(pi/2): {0}", task.ExtendedAttributes[0].NumericValue);
}

static Project CreateTestProjectWithCustomField()
{
    Project project = new Project();
    ExtendedAttributeDefinition attr = ExtendedAttributeDefinition.CreateTaskDefinition(CustomFieldType.Number, ExtendedAttributeTask.Number1, "Sine");
    project.ExtendedAttributes.Add(attr);

    Task task = project.RootTask.Children.Add("Task");

    ExtendedAttribute a = attr.CreateExtendedAttribute();
    task.ExtendedAttributes.Add(a);
    return project;
}

Calcul des fonctions générales

Les fonctions suivantes fournissent des évaluations logiques et conditionnelles :

1. Choose( index, choice-1, choice-2, ... , choice-n ) – sélectionne une valeur à partir d’une liste.
2. IIf( expr, truepart, falsepart ) – renvoie l’une des deux valeurs selon une condition.
3. IsNumeric( expression ) – vérifie si une expression est numérique.
4. IsNull( expression ) – vérifie si une expression est nulle.
5. Switch( expr-1, value-1, expr-2, value-2, ... ) – évalue les expressions dans l’ordre et renvoie la première valeur correspondante.

static void EvaluateChoose()
{    
    Project project = CreateTestProjectWithCustomField();
    
    // Set Formula
    project.ExtendedAttributes[0].Formula = "Choose(3, \"This is a\", \"right\", \"choice\")";
    
    // Print extended attribute value
    Task task = project.RootTask.Children.GetById(1);
    Console.WriteLine(task.ExtendedAttributes[0].TextValue);
}

static void EvaluateIsNumeric()
{
    string[] numericFormulas = { "IsNumeric('AAA')", "IsNumeric(1)", "IsNumeric(1<0)", "IsNumeric(\"1.1\")", "IsNumeric(Choose((2 + Sgn(2^-3)), 123, \"one two three\"))" };
    
    Project project = CreateTestProjectWithCustomField();
    
    foreach (string numericFormula in numericFormulas)    
    {
        // Set Formula
        project.ExtendedAttributes[0].Formula = numericFormula;

        // Print extended attribute value
        Task task = project.RootTask.Children.GetById(1);
        Console.WriteLine(task.ExtendedAttributes[0].TextValue);
    }
}

static void EvaluateSwitch()
{    
    Project project = CreateTestProjectWithCustomField();

    // Set Formula
    project.ExtendedAttributes[0].Formula = "Switch( 0 < 1, \"0 is lesser than 1\", 0 > 1, \"0 is greater than 1\")";

    // Print extended attribute value
    Task task = project.RootTask.Children.GetById(1);
    Console.WriteLine(task.ExtendedAttributes[0].TextValue);
}

Calcul des fonctions de texte

Les fonctions de manipulation de chaînes permettent le formatage et la comparaison :

1. Asc( string ) – renvoie le code ASCII du premier caractère.
2. Chr( charcode ) – renvoie le caractère correspondant à un code ASCII.
3. Format( expression, format, firstdayofweek, firstweekofyear ) – formate les nombres/les dates.
4. Instr( start, string1, string2, compare ) – trouve la position d’une chaîne dans une autre.
5. LCase( string ) – convertit en minuscules.
6. Left( string, length ) – extrait les caractères de gauche.
7. Len( string ) – renvoie la longueur de la chaîne.
8. LTrim( string ) – supprime les espaces en début.
9. Mid( string, start, length ) – extrait une sous-chaîne.
10. Right( string, length ) – extrait les caractères de droite.
11. RTrim( string ) – supprime les espaces en fin.
12. Space( number ) – renvoie une chaîne avec des espaces.
13. StrComp( string1, string2, compare ) – compare deux chaînes.
14. StrConv( string, conversion, LCID ) – convertit la chaîne selon la locale.
15. String( number, character ) – renvoie une chaîne répétée n fois.
16. Trim( string ) – supprime les espaces en début et en fin.
17. UCase( string ) – convertit en majuscules.

static void EvaluateStrConv()
{
    Project project = CreateTestProjectWithCustomField();
    Task task = project.RootTask.Children.GetById(1);

    // Set formulas and print extended attribute value
    project.ExtendedAttributes[0].Formula = "StrConv(\"sTring and sTRINg\",3)";
    Console.WriteLine(task.ExtendedAttributes[0].TextValue);
    project.ExtendedAttributes[0].Formula = "StrConv(\"sTring and sTRINg\",1)";
    Console.WriteLine(task.ExtendedAttributes[0].TextValue);
    project.ExtendedAttributes[0].Formula = "StrConv(\"sTring and sTRINg\",2)";
    Console.WriteLine(task.ExtendedAttributes[0].TextValue);
}

static void EvaluateStringFunction()
{
    Project project = CreateTestProjectWithCustomField();
    Task task = project.RootTask.Children.GetById(1);

    // Set formulas and print extended attribute value
    project.ExtendedAttributes[0].Formula = "String(5, 40)";
    Console.WriteLine(task.ExtendedAttributes[0].TextValue);
    project.ExtendedAttributes[0].Formula = "String(5, \"A\")";
    Console.WriteLine(task.ExtendedAttributes[0].TextValue);
    project.ExtendedAttributes[0].Formula = "String(-5, \"A\")";
    // #Error
    Console.WriteLine(task.ExtendedAttributes[0].TextValue);
}

Calcul des fonctions Date/Heure

Aspose.Tasks prend en charge à la fois les fonctions de date standard de style VB et les fonctions de planification spécifiques à MS Project :

1. CDate( expression ) – convertit une expression en date.
2. Date() – renvoie la date système actuelle.
3. DateAdd( interval, number, date ) – ajoute un intervalle à une date.
4. DateDiff( interval, date1, date2 ) – différence entre deux dates.
5. DatePart( interval, date ) – extrait une partie d’une date (année, mois, jour, etc.).
6. DateSerial( year, month, day ) – construit une date à partir de composants.
7. DateValue( date ) – convertit une chaîne en date.
8. Day( date ) – jour du mois.
9. Hour( time ) – extrait l’heure.
10. IsDate( expression ) – vérifie si une expression est une date valide.
11. Minute( time ) – extrait les minutes.
12. Month( date ) – extrait le mois.
13. Now() – renvoie la date et l’heure actuelles.
14. ProjDateAdd( date, duration, calendar ) – ajoute une durée en tenant compte du calendrier du projet.
15. ProjDateConv( expression, dateformat ) – convertit une date au format du projet.
16. ProjDateDiff( date1, date2, calendar ) – différence en tenant compte du calendrier du projet.
17. ProjDateSub( date, duration, calendar ) – soustrait une durée.
18. ProjDateValue( expression ) – évalue une expression de date.
19. ProjDurConv( expression, durationunits ) – convertit les durées entre unités.
20. ProjDurValue( duration ) – évalue une expression de durée.
21. Second( time ) – extrait les secondes.
22. Time() – renvoie l’heure système actuelle.
23. Timer() – nombre de secondes depuis minuit.
24. TimeSerial( hour, minute, second ) – construit une valeur temporelle.
25. TimeValue( time ) – convertit en heure.
26. Weekday( date, firstdayofweek ) – renvoie le jour de la semaine.
27. Year( date ) – extrait l’année.

Project project = CreateTestProject();
Task task = project.RootTask.Children.GetById(1);

ExtendedAttributeDefinition numberDefinition = ExtendedAttributeDefinition.CreateTaskDefinition(ExtendedAttributeTask.Number1, null);
project.ExtendedAttributes.Add(numberDefinition);

ExtendedAttribute numberAttribute = numberDefinition.CreateExtendedAttribute();
task.ExtendedAttributes.Add(numberAttribute);

// Set ProjDateDiff formula and print extended attribute value
numberDefinition.Formula = "ProjDateDiff(\"03/23/2015\",\"03/18/2015\")";
Console.WriteLine(numberAttribute.NumericValue);
numberDefinition.Formula = "ProjDateDiff(\"03/23/2015\",\"03/25/2015\")";
Console.WriteLine(numberAttribute.NumericValue);

ExtendedAttributeDefinition dateDefinition = ExtendedAttributeDefinition.CreateTaskDefinition(ExtendedAttributeTask.Date1, null);
project.ExtendedAttributes.Add(dateDefinition);
ExtendedAttribute dateAttribute = dateDefinition.CreateExtendedAttribute();
task.ExtendedAttributes.Add(dateAttribute);

ExtendedAttributeDefinition durationDefinition = ExtendedAttributeDefinition.CreateTaskDefinition(ExtendedAttributeTask.Duration4, "Custom duration field");
project.ExtendedAttributes.Add(durationDefinition);
ExtendedAttribute durationAttribute = durationDefinition.CreateExtendedAttribute();
task.ExtendedAttributes.Add(durationAttribute);

ExtendedAttributeDefinition textDefinition = ExtendedAttributeDefinition.CreateTaskDefinition(ExtendedAttributeTask.Text5, "Custom text field");
project.ExtendedAttributes.Add(textDefinition);
ExtendedAttribute textAttribute = textDefinition.CreateExtendedAttribute();
task.ExtendedAttributes.Add(textAttribute);

// Set ProjDateSub formula and print extended attribute value
dateDefinition.Formula = "ProjDateSub(\"3/19/2015\", \"1d\")";
Console.WriteLine(dateAttribute.DateValue);

// We can set ProjDurConv formula to duration-valued attribute as well as to text-valued attribute.

// Set ProjDurConv formula to duration-valued extended attribute and print its value.
durationDefinition.Formula = "ProjDurConv([Duration], pjHours)";
Console.WriteLine(durationAttribute.DurationValue);

// Set ProjDurConv formula to text-valued extended attribute and print its value.
textDefinition.Formula = "ProjDurConv([Duration], pjHours)";
Console.WriteLine(textAttribute.TextValue);

textDefinition.Formula = "ProjDurConv([Duration], pjWeeks)";
Console.WriteLine(textAttribute.TextValue);

// Set Second formula and print entended attribute value
numberDefinition.Formula = "Second(\"4/21/2015 2:53:41 AM\")";
Console.WriteLine(numberAttribute.NumericValue);

// Set Weekday formula and print entended attribute value
numberDefinition.Formula = "Weekday(\"24/3/2015\", 1)";
Console.WriteLine(numberAttribute.NumericValue);
numberDefinition.Formula = "Weekday(\"24/3/2015\", 2)";
Console.WriteLine(numberAttribute.NumericValue);
numberDefinition.Formula = "Weekday(\"24/3/2015\", 3)";
Console.WriteLine(numberAttribute.NumericValue);

Exemple pratique

Voici un scénario réel d’utilisation des formules :

    var project = new Project();
    var task = project.RootTask.Children.Add("Task 1");

    // Create an extended attribute with a custom formula
    ExtendedAttributeDefinition attrDef = ExtendedAttributeDefinition.CreateTaskDefinition(
        ExtendedAttributeTask.Text1, "Custom Formula");
        attrDef.Formula = "IIf([Duration] > 480, \"Long Task\", \"Short Task\")";
        project.ExtendedAttributes.Add(attrDef);

    var attr = attrDef.CreateExtendedAttribute();
    task.ExtendedAttributes.Add(attr);

    // The formula is automatically evaluated by Aspose.Tasks
    Console.WriteLine(task.Get(Tsk.Name) + " -> " + task.ExtendedAttributes[0].TextValue);

Principaux avantages du support des formules

• Compatibilité totale avec les formules MS Project.
• Capacité à automatiser champs dynamiques et logique conditionnelle.
• Prise en charge intégrée de fonctions prenant en compte le calendrier du projet (ProjDateAdd, ProjDateDiff, etc.).
• Simplifie les calculs complexes sans écrire de code C# personnalisé.

Voir aussi

• Travail avec les Extended Attributes
• Travail avec les formules
• Travail avec les calculs de projet