Unterstützung für die Auswertung von Funktionen in Formeln

Aspose.Tasks for .NET API unterstützt die Auswertung von als Formeln definierten Funktionen innerhalb der Extended Attributes eines Projekts.
Dadurch können Entwickler Berechnungen durchführen, die denen in Microsoft Project ähneln, wodurch es möglich wird, dynamische Felder zu implementieren, die von benutzerdefinierter Logik abhängen.

Die API bietet Unterstützung für die Auswertung der folgenden Funktionskategorien:

• Mathematische Funktionen
• Allgemeine Funktionen
• Textfunktionen
• Datums-/Zeitfunktionen

Diese Funktion ist besonders nützlich, wenn Sie Folgendes tun müssen:

• Projektberechnungen automatisieren,
• Benutzerdefinierte Geschäftsregeln implementieren,
• Die Formelkompatibilität zwischen MS Project und Aspose.Tasks sicherstellen.

Berechnung mathematischer Ausdrücke

Die folgenden mathematischen Funktionen werden unterstützt:

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;
}

Berechnung allgemeiner Funktionen

Die folgenden Funktionen bieten logische und bedingte Auswertungen:

1. Choose( index, choice-1, choice-2, ... , choice-n ) – wählt einen Wert aus einer Liste aus.
2. IIf( expr, truepart, falsepart ) – gibt abhängig von einer Bedingung einen von zwei Werten zurück.
3. IsNumeric( expression ) – prüft, ob ein Ausdruck numerisch ist.
4. IsNull( expression ) – prüft, ob ein Ausdruck null ist.
5. Switch( expr-1, value-1, expr-2, value-2, ... ) – wertet Ausdrücke der Reihe nach aus und gibt den ersten passenden Wert zurück.

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);
}

Berechnung von Textfunktionen

Zeichenkettenmanipulationsfunktionen ermöglichen Formatierung und Vergleich:

1. Asc( string ) – gibt den ASCII-Code des ersten Zeichens zurück.
2. Chr( charcode ) – gibt das Zeichen für einen ASCII-Code zurück.
3. Format( expression, format, firstdayofweek, firstweekofyear ) – formatiert Zahlen/Datumsangaben.
4. Instr( start, string1, string2, compare ) – findet die Position einer Zeichenkette innerhalb einer anderen.
5. LCase( string ) – wandelt in Kleinbuchstaben um.
6. Left( string, length ) – extrahiert die linksstehenden Zeichen.
7. Len( string ) – gibt die Zeichenkettenlänge zurück.
8. LTrim( string ) – entfernt führende Leerzeichen.
9. Mid( string, start, length ) – extrahiert eine Teilzeichenkette.
10. Right( string, length ) – extrahiert die rechtsstehenden Zeichen.
11. RTrim( string ) – entfernt nachfolgende Leerzeichen.
12. Space( number ) – gibt eine Zeichenkette mit Leerzeichen zurück.
13. StrComp( string1, string2, compare ) – vergleicht zwei Zeichenketten.
14. StrConv( string, conversion, LCID ) – konvertiert eine Zeichenkette entsprechend der Gebietsschemaeinstellungen.
15. String( number, character ) – gibt eine Zeichenkette zurück, die n Mal.
16. Trim( string ) – entfernt führende und nachfolgende Leerzeichen.
17. UCase( string ) – wandelt in Großbuchstaben um.

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);
}

Berechnung von Datums-/Zeitfunktionen

Aspose.Tasks unterstützt sowohl Standard-Datumsfunktionen im VB-Stil als auch MS Project-spezifische Planungsfunktionen:

1. CDate( expression ) – wandelt einen Ausdruck in ein Datum um.
2. Date() – gibt das aktuelle Systemdatum zurück.
3. DateAdd( interval, number, date ) – addiert ein Intervall zu einem Datum.
4. DateDiff( interval, date1, date2 ) – berechnet die Differenz zwischen zwei Daten.
5. DatePart( interval, date ) – extrahiert Teile eines Datums (Jahr, Monat, Tag usw.).
6. DateSerial( year, month, day ) – erstellt ein Datum aus Komponenten.
7. DateValue( date ) – wandelt eine Zeichenkette in ein Datum um.
8. Day( date ) – Tag des Monats.
9. Hour( time ) – extrahiert die Stunde.
10. IsDate( expression ) – prüft, ob ein Ausdruck ein gültiges Datum ist.
11. Minute( time ) – extrahiert die Minuten.
12. Month( date ) – extrahiert den Monat.
13. Now() – gibt aktuelles Datum und Uhrzeit zurück.
14. ProjDateAdd( date, duration, calendar ) – addiert eine Dauer unter Berücksichtigung des Projektkalenders.
15. ProjDateConv( expression, dateformat ) – konvertiert ein Datum in das Projektformat.
16. ProjDateDiff( date1, date2, calendar ) – berechnet die Differenz unter Berücksichtigung des Projektkalenders.
17. ProjDateSub( date, duration, calendar ) – zieht eine Dauer ab.
18. ProjDateValue( expression ) – wertet einen Datums-Ausdruck aus.
19. ProjDurConv( expression, durationunits ) – konvertiert Dauern zwischen Einheiten.
20. ProjDurValue( duration ) – wertet einen Dauer-Ausdruck aus.
21. Second( time ) – extrahiert die Sekunden.
22. Time() – gibt die aktuelle Systemzeit zurück.
23. Timer() – Anzahl der Sekunden seit Mitternacht.
24. TimeSerial( hour, minute, second ) – erstellt einen Zeitwert.
25. TimeValue( time ) – wandelt in eine Zeit um.
26. Weekday( date, firstdayofweek ) – gibt den Wochentag zurück.
27. Year( date ) – extrahiert das Jahr.

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);

Praxisbeispiel

Hier ein praxisnahes Szenario zur Verwendung von Formeln:

    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);

Wesentliche Vorteile der Formelauswertung

• Volle Kompatibilität mit MS Project-Formeln.
• Möglichkeit zur Automatisierung von dynamischen Feldern und bedingter Logik.
• Integrierte Unterstützung für Funktionen, die den Projektkalender berücksichtigen (ProjDateAdd, ProjDateDiff, usw.).
• Vereinfacht komplexe Berechnungen, ohne benutzerdefinierten C#-Code schreiben zu müssen.

Siehe auch

• Arbeiten mit Extended Attributes
• Arbeiten mit Formeln
• Arbeiten mit Projektberechnungen