2024-02-03

PowerShell Advanced Function Template

I have made this simple template to start a new PowerShell script file with a advanced function. It helps me to get the basics right from the beginning. Also it supports my effort to write all scripts with advanced functions.

The code for the template on a advanced function is on SQLAdmin GitHub (link).

PowerShell script documentation

To PowerShell is defined a syntax for comment-based help in scripts (about_Comment_Based_Help). And there are many more keywords than I have used above, but my personal PowerShell style is covered with these keyword. Feel free to create your own script template with our own personal selection of standard keywords.
Using only standard keywords ensure that your scripts can be presented in a central place with nice and useful documentation. And the presentation can be automatic updated without redundant documentation tasks.

Michael Sorens has on SimpleTalk posted a series of great posts about automatic documentation on a library of PowerShell scripts. The first post is called "How To Document Your PowerShell Library" where the basics are presented in a brilliant way.

Advanced function

If a script is evolving to become a central part of a process then you should elevate it by refactoring it to an advanced function.
The template above is for an advanced function, but not all possibilities are included.  The documentation on advanced functions (about_Functions_Advanced) and parameters on advanced functions (about_Functions_Advanced_Parameters).

A very important part of an advanced function is the CmdletBinding function attribute (about_Functions_CmdletBindingAttribute) that will make a function work like a compiled CmdLet. You can in most cases just use it blank and it will make a function work really nice as a CmdLet, but if you take some time to read and experiment you can create some awesome advanced functions. If you are looking into very large amounts of data you should take a look of the possibilities with CmdletBinding. More technical CmdletBinding is a PowerShell accelerator of the .NET class CmdletBindingAttribute that is a part of the namespace System.Management.Automation.

One thing that you will benefit from rather quick is the use of -Verbose or -Debug where it will by passed on through advanced functions. Then you will get ectended information not only from your own code but also from real CmdLets and .NET objects.

There are several articles that covers various facets of advanced functions ok, but my personal reference is, beside the documentation, the book „PowerShell In Depth“ (e.g. chapter 32) by Don Jones (@concentrateddon), Richard Siddaway (@RSiddaway) and Jeffery Hicks (@JeffHicks). Look for latest edition.

PowerShell script module

When you have refined the script, I think it is time to move the functionality to one or more PowerShell script modules. The general concepts about PowerShell modules are listed in the article „Windows PowerShell Module Concepts“ and short described in the MSDN article „Understanding a Windows PowerShell Module“. Right now I will focus on a script module as this text is about PowerShel scripting. There is a short and nice introduction in the MSDN article „How to Write a PowerShell Script Module“.

In the script template above I have indicated how to dynamically import a script module placed in a given path. If the script module is not signed and the PowerShell Execution Policy is somehow restricted – which it should be! – you can't import a module placed outside the local computer, e.g. on a file share through a UNC path.

PowerShell script modules are defined and stored in psm1-files, but looks a lot like plain script files. If you use the script template above for a script module the module import and the final lines with invokation should be removed. The invokation should be in the script file importing the script module.

There are several benefits of using PowerShell script modules. Many of them you will see when you start using them...
One thing that surprised me was the value of unit testing the script code.

Michael Sorens (again) has on SimpleTalk written the great article „Further Down the Rabbit Hole: PowerShell Modules and Encapsulation“ on PowerShell modules and the surroundings with some very valuable guidelines.

History

2017-03-15 : Blog post created on SQLAdmin blog.
2017-05-17 : Section about script documentation added. Inspired by comment from my old friend and colleague Jakob Bindslet.
2017-06-14 : Section about PowerShell script module added.
2017-07-04 : Section about PowerShell Advance function added.
2017-11-10 : Blog post text migrated from SQLAdmin blog and code to Github.
2024-02-03 : Blog post migrated (back) to SQLAdmin. Code migrated to SQLAdmin Github.

Path environmental variable with PowerShell

See defined paths
$env:path.Split(';')

Add new path
[string]$JdbcAuthPath = 'C:\temp\Install-Manual\sqljdbc6220\sqljdbc_6.2\enu\auth\x64'
[string]$OldPath = [System.Environment]::GetEnvironmentVariable('Path')
[string]$NewPath = $OldPath + ';' + $JdbcAuthPath
[Environment]::SetEnvironmentVariable('Path', $NewPath, [System.EnvironmentVariableTarget]::Machine)

Test new path
(new session)

Remove path
[string]$OldPath = [System.Environment]::GetEnvironmentVariable('Path')
[string]$NewPath = $OldPath.Replace($JdbcAuthPath, $null)
[Environment]::SetEnvironmentVariable('Path', $NewPath, [System.EnvironmentVariableTarget]::Machine)

Test new path
(new session)

DSC Environment Resource

(https://docs.microsoft.com/en-us/powershell/dsc/environmentresource) 

History

2024-02-03 Migrated from Azure Admin blog.

2024-01-28

Integrated Security = SSPI

 The term Integrated Security = SSPI is a element in a connection string for an application to get access to a data source using a OLEDB or SqlClient provider. Usually it is just used because it is recommended by someone trustworthy.

SSPI is an abbreviation to Security Support Provider Interface which is a general implementation of the Generic Security Services Application Program Interface (GSSAPI). The interesting thing is that SSPI makes it possible to get the most secure authentication in a given context. In Windows it is at least a Kerberos or NTLM authentication. When possible you will get the more secure - and faster - Kerberos authentication. This is done by a negotiation, where some parameters like rank can be configured in Windows. The Windows configuration can be through Group Policies, both local and domain.

In relation to SSPI Kerberos and NTLM are Security Support Providers (SSPs) speaking Windows lingo. The documentation from Microsoft says that you can write our own SSP, but I couldn't find many details on the subject.

Speaking about Microsoft documentation the SSPI documentation as spred across Windows Server documentation on Windows Authentication with "Security Support Provider Interface Architecture" and Windows App Development on Remote Procedure Call (RPC) with "Security Support Provider Interface (SSPI)". In general I find it somewhat difficult to find documentation on the involved components in a login and authentication process.

Using SSPI is done with different parameters and values on each driver or provider.
With the SqlClient the keyword to the ConnectionString property is "Integrated Security" and the value is "SSPI" - which is „strongly recommended“ by Microsoft. Please notice that with SqlClient 5 the namespace is changed from System.Data.SqlClient to Microsoft.Data.SqlClient as the SqlClient component is removed from the .NET framework and is now available as a NuGet package.
With the ODBC driver the keyword is "Trusted_Connection" and the value is "Yes" which is an example on the big variations on both keywords and values. If you are using a driver from another vendor than Microsoft or a driver for another environment you should be very aware on these details as they can really bite you.

 

2024-01-23

PowerShell SMO by SqlServer module

Install SqlServer module:

Install-Module -Name sqlserver

Typical warning:

Untrusted repository
You are installing the modules from an untrusted repository. If you trust this repository, change its
InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to install the modules from 'PSGallery'?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): y


See installed module:

Get-Module -Name SqlServer -ListAvailable


Import SqlServer module in PowerShell session:

Import-Module -Name SqlServer


Create SMO Server object:

$smoServer = New-Object Microsoft.SqlServer.Management.Smo.Server '(local)\SSDB2019'

See SMO Server object information:

$smoServer.Information

2024-01-01

Top-ten posts 2023

2023 was – again – a year with far less posts than planned. Fortunately some elder posts still generate some activity on this blog.

The top-ten 2023 post list is something like Top-ten posts 2022.

RankMoveRank 2022TitleViewsCreated
101SqlBulkCopy with PowerShell1.9502017-07-30
2>9>10High performance script timer8142020-01-03
3+14ISO 8601 date formatting using PowerShell4792008-08-14
4>7>10ISO 4217 Currency list4252012-06-26
5+38SQL Server Agent schedule owner3602010-02-08
6>5>10Team Foundation Server on a single server3502018-09-19
7-16DBCC CHECKDB with PowerShell3062014-10-09
8>3>10Start shared HTA with PowerShell2712012-09-13
9>2>10VLF count2472011-01-11
10010Audit Log for Analysis Services2042014-01-08

This year there are several new items on the Top-ten. My personal biggest surprise is the item on ISO 4217.
But – still my favority ISO is 8601. The oldest post is more than ten years old, which is I find both interesting and disturbing.

The posts in this blog are personal notes rather than public presentations. This is why I am fine with the low number of views.