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.

![Reserve script number](../../../.attachments/How-to-create-scripts/ReserveScriptNumber.png)

> 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 <y> in the example).  
`GetSqlQueries()` should `yield return` your sql script(s) - SEE NEXT SECTION BEFORE WRITING IT.

```csharp
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.
```csharp
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 <xyz>' 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  
SQLScriptCollection`X`.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:

```xml
<Script Name="" ScriptNumber="">
    <Create>
      <![CDATA[ { Create Query } ]]>
    </Create>
    <Alter>
      <![CDATA[ { Alter Query } ]]>
    </Alter>
</Script>
```
```xml
<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.

> :exclamation: New scripts should be added at the bottom of the file, before the templates. :exclamation:

> :exclamation: All database changes should be tested by using local or test database before commiting any changes. :exclamation:

## 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:

```csharp
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.  


```csharp 
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.

> :exclamation: After testing return the version number to `1.0.0.0` or undo changes done to `AssemblyVersionInfo.cs` file. :exclamation: