How to create synopsis automatically in VScode

My daily work contains a lot of scripting in powershell. Because powershell is a scripting and automation language, I also wanted to automate the task of scripting. And also because I’m really lazy… 😉

My goal: having a shortcut to insert automatically a synopsis with personal /dynamic informations. Also add a history with timestamp so on…

Here is my manual to achieve this goal.

First of all, VScode has no built-in option to reach our goal. So you have to install an external VScode extension which is named:
psioniq File Header

If you click on the content table there is a lot explanation for this extension. I ‘ll try to summarize it. First of all, open VSCode and go to the settings.json file. (go to “settings” and search for “json”)

if json settings are empty you may have a look at my older post to change the default language to powershell see it here.

I’ll try to explain psi header configuration in separated topics

psi-header.config

basic settings for the generated header, looks like this in my configuration

"psi-header.config": {
		"forceToTop": true,
		"blankLinesAfter": 4,
		"license": "Custom"
	},

psi-header.license-text

this is where you can write that you are not responsible for anything… bla…bla

	"psi-header.license-text": [
		"Permission is hereby granted, free of charge, to any person obtaining a copy",
		"of this software and associated documentation files (the Software), to deal",
		"in the Software without restriction, including without limitation the rights",
		"to use copy, modify, merge, publish, distribute sublicense and /or sell",
		"copies of the Software, and to permit persons to whom the Software is",
		"furnished to do so, subject to the following conditions:",
		"",
		"The above copyright notice and this permission notice shall be included in all",
		"copies or substantial portions of the Software.",
		"",
		"THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR",
		"IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,",
		"FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE",
		"AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER",
		"LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,",
		"OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE",
		"SOFTWARE.",
	],

psi-header.variables

as mentioned before psi header has to know who is working on this header.

"psi-header.variables": [
		["company", "blog.it-koehler.com"],
		["author", "Alexander Koehler"],
		["authoremail", "blogging@it-koehler.com"],
		["website", "https://blog.it-koehler.com/en/"],
		["initials", "AK"]
	],

psi-header.lang-config

define the language you want to use this header (this is important because every language has its own way to comment things out)

{
			"language": "powershell",
			"begin": "<#",
			"end": "#>",
			"prefix": "",
        }

psi-header.templates

finally the header it self, here you can write whatever you want (not completely but nearly)

"psi-header.templates": [
		{
			"language": "*",
			"template": [
				"#### requires ps-version 3.0 ####",
				"<#",
				".SYNOPSIS",
				"<Overview of script>",
				".DESCRIPTION",
				"<Brief description of script>",
				".PARAMETER <Parameter_Name>",
					"<Brief description of parameter input required. Repeat this attribute if required>",
				".INPUTS",
				"<Inputs if any, otherwise state None>",
				".OUTPUTS",
				"<Outputs if anything is generated>",
				".NOTES",
					"   Version:        0.1",
					"   Author:         <<author>>",
					"   Creation Date:  <<filecreated('dddd, MMMM Do YYYY, h:mm:ss a')>>",
					"   File: <<filename>>",
				  	"   Copyright (c) <<year>> <<company>>",
					"HISTORY:",
					"Date      \t          By\tComments",
					"----------\t          ---\t----------------------------------------------------------",
					"",
				".LINK",
					"   <<website>>",	
				"",
				".COMPONENT",
				" Required Modules: ",
				"",
				".LICENSE",
					"<<licensetext>>",
				" ",  
				".EXAMPLE",
				"<Example goes here. Repeat this attribute for more than one example>",
				"#",
				"",
				"#---------------------------------------------------------[Initialisations]--------------------------------------------------------",
				"",
				"#---------------------------------------------------------[Variables]--------------------------------------------------------",
				"#Log File Info",
				"#$sLogPath = ",
				"#$sLogName = script_name.log",
				"#$sLogFile = Join-Path -Path $sLogPath -ChildPath $sLogName",
				"",
				"#---------------------------------------------------------[Modules]--------------------------------------------------------",
				"",
				"#---------------------------------------------------------[Functions]--------------------------------------------------------",
			],
			"changeLogCaption": "HISTORY:",
			"changeLogHeaderLineCount": 2,
			"changeLogEntryTemplate": [
				"<<dateformat('YYYY-MM-DD-hh-mm-a')>>\t <<initials>>\t"
			]
		},
	]

Have a look at the “history” part. I ‘ll explain later on. So let’s all put together and put it to your settings.json file. See my complete file:

{
    "powershell.powerShellExePath": "C:\\WINDOWS\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
    "files.defaultLanguage": "powershell",

	"psi-header.config": {
		"forceToTop": true,
		"blankLinesAfter": 4,
		"license": "Custom"
	},
	
	"psi-header.license-text": [
		"Permission is hereby granted, free of charge, to any person obtaining a copy",
		"of this software and associated documentation files (the Software), to deal",
		"in the Software without restriction, including without limitation the rights",
		"to use copy, modify, merge, publish, distribute sublicense and /or sell",
		"copies of the Software, and to permit persons to whom the Software is",
		"furnished to do so, subject to the following conditions:",
		"",
		"The above copyright notice and this permission notice shall be included in all",
		"copies or substantial portions of the Software.",
		"",
		"THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR",
		"IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,",
		"FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE",
		"AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER",
		"LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,",
		"OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE",
		"SOFTWARE.",
	],
	"psi-header.variables": [
		["company", "blog.it-koehler.com"],
		["author", "Alexander Koehler"],
		["authoremail", "blogging@it-koehler.com"],
		["website", "https://blog.it-koehler.com/en/"],
		["initials", "AK"]
	],
	"psi-header.lang-config": [
		{
			"language": "powershell",
			"begin": "<#",
			"end": "#>",
			"prefix": "",
        }
	],
	"psi-header.templates": [
		{
			"language": "*",
			"template": [
				"#### requires ps-version 3.0 ####",
				"<#",
				".SYNOPSIS",
				"<Overview of script>",
				".DESCRIPTION",
				"<Brief description of script>",
				".PARAMETER <Parameter_Name>",
					"<Brief description of parameter input required. Repeat this attribute if required>",
				".INPUTS",
				"<Inputs if any, otherwise state None>",
				".OUTPUTS",
				"<Outputs if anything is generated>",
				".NOTES",
					"   Version:        0.1",
					"   Author:         <<author>>",
					"   Creation Date:  <<filecreated('dddd, MMMM Do YYYY, h:mm:ss a')>>",
					"   File: <<filename>>",
				  	"   Copyright (c) <<year>> <<company>>",
					"HISTORY:",
					"Date      \t          By\tComments",
					"----------\t          ---\t----------------------------------------------------------",
					"",
				".LINK",
					"   <<website>>",	
				"",
				".COMPONENT",
				" Required Modules: ",
				"",
				".LICENSE",
					"<<licensetext>>",
				" ",  
				".EXAMPLE",
				"<Example goes here. Repeat this attribute for more than one example>",
				"#",
				"",
				"#---------------------------------------------------------[Initialisations]--------------------------------------------------------",
				"",
				"#---------------------------------------------------------[Variables]--------------------------------------------------------",
				"#Log File Info",
				"#$sLogPath = ",
				"#$sLogName = script_name.log",
				"#$sLogFile = Join-Path -Path $sLogPath -ChildPath $sLogName",
				"",
				"#---------------------------------------------------------[Modules]--------------------------------------------------------",
				"",
				"#---------------------------------------------------------[Functions]--------------------------------------------------------",
			],
			"changeLogCaption": "HISTORY:",
			"changeLogHeaderLineCount": 2,
			"changeLogEntryTemplate": [
				"<<dateformat('YYYY-MM-DD-hh-mm-a')>>\t <<initials>>\t"
			]
		},
	]

}

Save your json file and the new settings will be ready.

How about inserting this new header in scripts, therefore I create a new powershell file with ctrl+n and save it as “header-test.ps1“. When we already diskuss shortcuts, to insert the new header you need to use the following “short” cut: ctrl+alt+h (two times). If you press this only one time vscode is awaiting the next step… see the right corner of vscode.

two times this little shortcut… hooray there is my synopsis. Not that bad.

If it is really difficult to remember shortcuts you can also use the command palette with “F1” and type “header”.

Remember the history, already mentioned in this article? For me it is important to write some comments. Psi-header support also a little history feature. You may have seen in the config.json

"changeLogCaption": "HISTORY:",
			"changeLogHeaderLineCount": 2,
			"changeLogEntryTemplate": [
				"<<dateformat('YYYY-MM-DD-hh-mm-a')>>\t <<initials>>\t"
			]

This code only adds a history line inside your header, so you can comment changes or anything you want. Lets have a look at this feature. Shortcut: ctrl+alt+c (two times) or F1 and type “header change”

Now you are able to insert a synopsis in every powershell script really easily. And you can also comment some changes in history.

If you like this article please let me know and click on helpful. Thanks for reading and have fun with VScode.