Masterarbeit/QuellCode/CentronERP/docs/guides/database/create-scripts.md

How to create scripts

In order to do any changes over some database table, there are couple of things you need to do first.

Reserve the script number

The .excel sheet can be found in Teams c-entron Entwickler group in the files tab Datenbankupdate 2 1.xlsx. What you have to do there is just write a number - known as a Script number, which has to be for one bigger than the
number used before. Enter the date of the day when the script number is being reserved. Write a short description about what the script is.
Enter the version from which the change will be included and in the last column your own name.

Note: If there are more scripts that have to be executed, all of them can use the same Script number.

Writing your script method class

Navigate to Centron.BL/Administration/Scripts/ScriptMethods/Scripts and create a class with the name ScriptMethod<x>.cs where x is your script number.
In the class you have to implement BaseScriptMethod and with that the property ApplicationVersion and the method GetSqlQueries().

ApplicationVersion should be the current version and only ever change the Buildversion part (the one marked with in the example).
GetSqlQueries() should yield return your sql script(s) - SEE NEXT SECTION BEFORE WRITING IT.

internal class ScriptMethod<x> : BaseScriptMethod
{
    public override Version ApplicationVersion => new(2, 0, <y>, 0);

    public override IEnumerable<string> GetSqlQueries()
    {
        yield return "<here goes your script>";

        OR

        yield return ScriptHelpers.AddColumnIfNotExists("<your table>", "<your column>", ..);
    }
}

Writing your script

There are 2 main ways to write your sql scripts, depending on your needs.

Using ScriptHelpers

For certain tasks the ScriptHelpers.cs will generate the actual sql for you and you just have to call the correct method. Here are some of the main tasks you can use it for, but check for yourself if scripthelpers can help you.

• AddColumnIfNotExists()
• AddTableIfNotExists()
• AddRightIfNotExists()
• AddIndexIfNotExists()
• AddForeignKeyIfNotExists()

If there is a scripthelper method that can help you, you really should use it.

Using a scripthelper does not exonerate you from testing your script!

See (disregard the properties in these examples):
ScriptMethod11355.cs
ScriptMethod11358.cs

Plain SQL

This is used for everything not covered by ScriptHelpers and allows you to just write your own scripts. If you feel like what you're writing can be automated relativly easily, think about adding method(s) to ScriptHelpers so it's reusable.

See (disregard the properties in these examples):
ScriptMethod11359.cs
ScriptMethod11364.cs

Writing a C# script

If you need to or prefer to write data migration using C# instead of pure SQL, you can do so by overriding the ExecuteScript() method instead.

public override Result ExecuteScript(DAOSession session)
{
    // your code here
    return Result.Success();
}

You can use the DAOSession to interact with the database while having access to the full C# codebase. If you need both C# and SQL, it is recommended to separate the migration into two separate scripts.

Adding comments

Depending on the complexity of your script you either should (if less complex) or must (if complex) add a comment on what changed, why and for views it'd be nice to have a 'this script supercedes script ' with xyz being the last change to that view. You can mostly reuse the text from Datenbankupdate 2 1.xlsx here.

Legacy ways

The below section is an old way to write script methods and should no longer be used.

Write the script

In c-entron.NET solution, under the Centron.BL.Administration.Scripts.ScriptMethods.SqlStatements can be found a file named
SQLScriptCollectionX.xaml, where X represents the latest collestion of scripts and is the file that is supposed to be edited.
By scrolling to the bottom, you can find templates that are being used:

<Script Name="" ScriptNumber="">
    <Create>
      <![CDATA[ { Create Query } ]]>
    </Create>
    <Alter>
      <![CDATA[ { Alter Query } ]]>
    </Alter>
</Script>

<Script Name="" ScriptNumber="">
    <UpdateQuery>
      <![CDATA[ { Update Query } ]]>
    </UpdateQuery>
</Script>

Which template to use?

First template is used to do manipulations with views, functions and store procedures.

Second template is supposed to be used for any table create or update actions, for example: add table, add/remove new column,
add/delete data, drop,...
For any table updates, especially if it's about adding or removing column or adding the whole new table, you should
do a check first if the column or table exists and only then the rest of the query should be executed.

❗ New scripts should be added at the bottom of the file, before the templates. ❗

❗ All database changes should be tested by using local or test database before commiting any changes. ❗

Write new class

For every database change, there has to be a new script method class created. In c-entron.NET solution, under the
Centron.BL.Administration.Scripts.ScriptMethods can be found a file named ScriptMethodsCollection.cs. In this
file a new internal class has to be created, which contains the script number in the name, eg. ScriptMethod10806.

Here is a basic template for it:

internal class ScriptMethod10806 : BaseScriptMethod
{
    public override int ScriptNumber => 10806;
    public override Version ApplicationVersion => new Version(2, 0, 1912, 0);
    public override ScriptMethodKind MethodKind => ScriptMethodKind.TableManipulation;
    public override ScriptCollectionSource ScriptCollection => ScriptCollectionSource.SQLScriptCollection4;

    public override IEnumerable<string> GetScripts()
    {
        yield return "SomeScriptName";
    }
}

Note: New script method class should be added at the bottom of the file.

There are few things that need to be considered before blindly using this template. Depending on what the script is about,
you will have to do some changes to the template.

If your script is a creation or change of view, then you are supposed to do the override of GetViews() method. If the script has to do
something with triggers, then you should use GetTriggers(), or based on what the script is about just use the propper override method.
All of the methods provided can be found in BaseScriptMethod.cs class.

public override IEnumerable<string> GetViews()
{
    yield return "SomeScriptName";
}

Also, one other thing that should be considered, while using the template, is the ScriptMethodKind. Depending on what the action
of the script is, the proper ScriptMethodKind should be used. There are several of them:

• TableManipulation - this kind is very self explanatory, includes any table change/update
• SystemData - inserting or updating data in the table
• Script
• WithoutTransaction

After doing all those steps, the best way to test if the script is going to execute without any issues is to actually
start the web servie, but with a small change. In c-entron.NET solution, under solution items folder, there is a file named AssemblyVersionInfo.cs
which contains the versions.
Normally, the versions are set to 1.0.0.0. For the testing purposes or just to execute scripts that were previously added
and keep your local database in sync, you should change the versions to 3.0.0.0.
Save it and start the web service alone or in combination with the UI (doesn't really matter).
In the console window, you can track what scripts were executed and if the execution was successful, otherwise you will know
that something went wrong because it will be displayed in red.

❗ After testing return the version number to 1.0.0.0 or undo changes done to AssemblyVersionInfo.cs file. ❗