Documentation

Introduction

Welcome to FileSync, a PowerShell tool designed to simplify file synchronization between two locations while offering advanced features for better control and flexibility. Developed with user convenience and efficiency in mind, FileSync makes the process of managing files across different directories effortless, ensuring seamless synchronization and comprehensive logging of changes.

Concretization of the task

We decided to create our script based on the suggestion from Mr. [redacted]. We however did not only create his example, but we added some of our own features, like remembering the source and destinationpath, removing all information, sync level 1 files only and many more.

User Story

The use case of this script is, when User X wants to sync his files on his drives, but only wants to sync the files in the first level of his source directory and wants to remove the other files, that exist in the destination directory and not in the source directory, then this script is exactly what User X is looking for.

What is FileSync?

FileSync is a PowerShell tool that synchronizes files between two locations and logs the changes. There are many more features that you can explore.

Features

FileSync has the following features:

Synchronizes files between two locations
Logs changes
Remembers the last source and destination paths
Copy or move files
Keep or remove information about the source files

and many more:

A full list of features:

Synchronizes files between two locations
Logs changes
Remembers the last source and destination paths
Copy or move files and directories
Copy or move files and directories from source to destination or destination to source
Keep or remove information about the source files
Copy or move files and directories from all levels or level 1 only
Remove files from the destination that don't exist in the source anymore
Remove the script files in a clean and proper way. (Does not leave file traces)

Layout

We opted for a console layout, because we found that more time efficient than creating an extra GUI. We did however make the console as user-friendly as possible. (see picture above and below)

For the program procedure, see the picture below.

Script

We defined the variables that were script-wide important at the beginning. This helped us to keep things sorted.

# Variables
[int] $menuinput # User input for menu selection
[string] $syncoptions # Sync options
# Project related variables
[string] $ProjectName = "FileSync"
[string] $ProjectVersion = "0.0.0.6"
[string] $Tempfolder = [Environment]::GetFolderPath( 'LocalApplicationData' ) + "\FileSync"
# Source and destination paths for file synchronization
[string] $sourcepath = ""
[string] $Destinationpath = ""
# File paths for settings and logs
[string] $settingsFilePath = "$Tempfolder\Settings.dll"
[string] $ErrorLogFilePath = "$Tempfolder\ErrorLog.log"
[string] $logFilePath = "$Tempfolder\FileSync.log"
[string] $logMessage
[int] $corrupted
# Sync options as strings
[string] $00000 = "[all contents]`n[Source to Destination]`n[without deleting files and directories that no longer exist in the source]`n[keeping all file information]`n[copying files and directories]"
# ...for each option...

We created multiple functions in order to handle the different phases of the script. Our logic of the script is following:

Script process

The first time you start FileSync, it checks with the function: Startup if all resource files exist and if they do it reads out the information from the important files. We achieved that by importing the settings' content and checked if the line matched with the line we were looking for. After it did, we used regex techniques to save them globally to the corresponding variable (see ln: 571 - 578). However, if one or all of the files were missing or corrupted, Startup would call a new function called Setup with the correct parameters and that would create the missing or corrupted file*s.
If there are some problems while booting, the function Setup would jump into action with the correct parameters. It would create the file*s and fill them with the correct content. (see ln: 616 - 733)
If it booted correctly, Startup calls the function Menu. This prints the menu as seen below. From there we can choose many different options. (see ln: 65 - 148)
=========================================== | FileSync (ver.0.0.0.6) | |_________________________________________| | (1) Sync now | | (2) Current Configuration | | (3) Reconfigure | | (4) Open Log | | (5) Help | | | | (95) Remove all Information | | (99) Exit | |_________________________________________| Please select an option:
The next function we will look at, are the preSync and FileSync functions (preSync is called in option 1 of the menu). In the preSync function we did something very interesting. Instead of adding multiple if-else Statements and then run the result with those options, we decided to create an encoding. After each question we added the Input (0 or 1) to the variable [string] $syncoptions # Sync options. This meant that at the end of five questions we would have filled $syncoptions with 0 or 1 and that meant, we could use a switch to call up the FileSync function with the encoding (see ln: 150 - 426). Example: FileSync -run_what $robocopy_10100 -write_what $10100. Now we had a very small FileSync function, because the decision-making was done already in the preSync. In the FileSync function we also added a switch to check the return codes from robocopy and print the corresponding message. (We used robocopy for the syncing, as it is very handy and extra built for such operations). This would not have worked, if we had moved the variable declaration block in preSync to the beginning of the script, since the source and destination paths should only be filled into the commands after they were known! (see FileSync ln: 498 - 572 and PreSync ln: 165 - 497)
One last function we will look at is the log function. Since we log almost everything the script does, we decided to create a log function. This log function required two things. Firstly the log message and secondly the log level (level 1 being log and level 2 being error). What the logging function does is, it adds to the message "at dd-MM-yyyy HH:mm.sss" and then appends it to the log file. Now the smart part: Instead of always crashing when the log file does not exist, it just returns to the place it came from, if it did not exist. This is very smart, because we then don't have to take care of the file-not-found error when the user deletes the log file while FileSync is running. (see ln: 735 - 756)

Please note, that we did not explain all the functions, but rather the most important ones.

Testing

We performed several tests. You can use the scrollbar at the bottom of the table to look at all columns:

Test Number	Test Type	Test Data	Reason	Expected Outcome	Actual Outcome	Pass?	Notes
1	Valid	Starting up the script for the first time ever (doesn't matter which Powershell version is used for the FIRST startup)	To see if it'll create all the folders, files and if it'll ask you for a new sourcepath and destination path	Valid	Valid	Pass	None
2	Invalid	IN POWERSHELL 7: Changing the sourcepath in settings.dll file manually inside of the following path depending on the testers device "C:\Users\[user]\AppData\Local\FileSync\Settings.dll"	To Test if the script is started once more that it'll ask you to set a new sourcepath	Invalid	Invalid	Pass	None
3	Invalid	IN POWERSHELL 1 (Same test as in Test Number 2, but in powershell 1): Changing the sourcepath in settings.dll file manually inside of the following path depending on the testers device "C:\Users\[user]\AppData\Local\FileSync\Settings.dll"	To Test if the script is started once more that it'll ask you to set a new sourcepath	Invalid	Invalid	Not Pass	Did not pass due to Powershell 5.1 making an endless error loop (That's why Powershell 7.4 is recommended)
4	Valid	menuinput = 1	Enter a valid input for the menuinput to check if it starts the syncing process.	Valid	Valid	Pass	None
5	Valid	menuinput = 2	Enter a valid input for the menuinput to check if it displays the current configurations of source- and destinationpath.	Valid	Valid	Pass	None
6	Valid	menuinput = 3	Enter a valid input for the menuinput to check if it displays the current configurations of source- and destinationpath AND ask for new source- and destinationpath.	Valid	Valid	Pass	None
7	Valid	menuinput = 4	Enter a valid input for the menuinput to check if it prints the log file into the terminal.	Valid	Valid	Pass	None
8	Valid	menuinput = 5	Enter a valid input for the menuinput to check if it prints the log file into the terminal.	Valid	Valid	Pass	None
9	Valid	menuinput = 95 AND check manually if the folder/information was deleted that was created by the script, either check if the following path exists: "C:\Users\[user]\AppData\Local\FileSync" or check the recycling bin if the folder is in there	Enter a valid input for the menuinput to check if it deletes all information that was created by the script.	Valid	Valid	Pass	None
10	Valid	menuinput = 99	Enter a valid input for the menuinput to check if it'll exit the Terminal.	Valid	Valid	Pass	None
11	Invalid	menuinput = 70	Enter an invalid input for the menuinput to check if it'll print the correct Invalid text message.	Invalid	Invalid	Pass	None
12	Valid	syncconfirmation = p	Enter p (proceed) to see if it'll actually proceed with the Syncing dialogue	Valid	Valid	Pass	None
13	Invalid	syncconfirmation = dog	Enter an invalid input for the syncconfirmation to check if it'll redirect you to the menu again.	Invalid	Invalid	Pass	None
14	Invalid	Manually deleting the FileSync.log file from the FileSync folder (C:\Users\[user]\AppData\Local\FileSync\FileSync.log)	To Test when the script is started once more, that it'll detect the missing FileSync.log file and creates it again.	Invalid	Invalid	Pass	Though be advised, any activity that was done before deleting the log file will not be restored.

Conclusion

We were very interested and motivated to program this script. We both loved the challenges and were eager to solve the various problems that FileSync has brought us.

In the end, we came to the conclusion, that we would definitely love to do this again.

Last modified: 19 March 2024