VSCode automatische Beschreibung erstellen

The estimated reading time 8 minutes

Meine tägliche Arbeit befasst sich viel mit PowerShell Skripten. Deshalb wollte ich das erstellen der Synopsis (also der Beschreibung innerhalb des Skriptes) ebenfalls automatisieren. Ein weiterer Grund ist einfach, dass ich nur zu faul bin, das jedes Mal aufs neue zu erstellen…

Mein Ziel: ich würde gerne an Hand eines Tastenkürzels automatisch eine neue Beschreibung einfügen, diese soll persönliche /dynamische Informationen wie Zeitstempel und Verlauf enthalten.

Nun also die Anleitung, wie dies mit VS Code erreicht werden kann.

Zunächst kann VS Code dies nicht „by Design“ das heißt es muss eine Erweiterung aus dem Store installiert werden.
psioniq File Header

Es gibt bei dieser Erweiterung jede Menge Infos, welche unter Details zu finden sind. im Nachgang eine kleine Zusammenfassung. Zunächst muss die settings.json Datei geöffnet werden, diese kann man einfach über „Datei->Einstellungen-> Suche nach ‚json‘ „

Sollte die Datei „settings.json“ leer sein, ist das nicht schlimm. Ihr könnt in einem älteren Artikel (siehe hier) erfahren, wie man die Standardprogrammiersprache auf PowerShell umstellt.
Ich werde nun versuchen psi header Konfiguration in einzelnen Punkten zu erklären. Die folgenden Punkte müssen in die „settings.json“ Datei eingefügt werden.

psi-header.config

es werden zunächst die Grundeinstellungen definiert

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

psi-header-license-text

In dieser Sektion könnt ihr jegliche Verantwortung abstreiten und so weiter…

	"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.lang-config

Natürlich muss VSCode wissen, welche Programmiersprache bei dem Header verwendet wird, da sonst das „Auskommentieren“ nicht funktioniert. Es gibt hier doch erhebliche Unterschiede.

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

psi-header.templates

Endlich kann nun der eigentliche Header erstellt werden.

"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"
			]
		},
	]

Schaut euch auf jeden Fall mal noch den „History“ Teil an, ich werde diesen aber später nochmals erklären. Nun noch die kompletten Einstellungen, damit ihr diese direkt in die „settings.json“ kopieren könnt:

{
    "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/"],
		["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"
			]
		},
	]

}

Die Datei muss natürlich noch gespeicher werden und schon sind die Änderungen aktiv. Die Datei kann geschlossen werden.
Wie lässt sich jetzt nun ein Header direkt in eine Datei einfügen? Dazu erstelle ich mir eine leere Datei mit STRG+N und speichere diese als „header-test.ps1“. Wie bereits erwähnt soll der Header nachher per Shortcut bzw. Tastenkürzel eingefügt werden. Dazu muss nun STRG+ALT+H gedrückt werden (zwei Mal). Wird die Kombination nur einmal gedrückt erwartet VSCode weitere Schritte… siehe untere rechte Ecke.

Also zweimal Gedrückt und siehe da, unser Header erscheint.

Wenn ihr euch das Tastenkürzel nicht merken könnt, dann ist dies auch über F1 und Suche möglich „Header“

So, nun noch einige Worte zum Thema History, was bereits zu Beginn angesprochen wurde. Für mich ist es immer wichtig Kommentare zuschreiben und auch eine kleine Änderungshistorie zu schaffen. Psi-header unterstützt dies ebenfalls. Vielleicht habt ihr folgende Zeilen in meinem settings.json gesehen.

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

Diese Passage ermöglicht es eine kleine Historie im Header zu führen, dies kann ebenfalls mit einem Tastenkürzel erledigt werden STRG+ALT+C (zweimal) oder eben über F1 „header change“.

Nun könnt ihr in jegliches Skript sehr einfach eine kleine Beschreibung hinzufügen und auch Änderungen dokumentieren.
Wenn euch der Artikel gefallen hat, dann schreibt einen Kommentar oder drückt auf „Helpful“. Vielen Dank fürs Lesen. Weitere Artikel folgen.

Was this article helpful?
YesNo
0 0 votes
Article Rating
Abonnieren
Benachrichtige mich bei
guest
0 Comments
Newest
Oldest Most Voted
Inline Feedbacks
View all comments