Scripting Operations Framework

Active Directory & SQL: Web Portal configuration

2009-05-29T09:53:00.002+02:00

Previous part of this post is HERE!

The last part of the Web Portal deployment is the configuration!

Of course, configuration depends on Web Portal itself and the integration environment. This post is about to share some powreshell tips around Active Directory and SQL which are the common technologies used for a Web Portal.

Here, our Web Portal needs a dedicated organizationnal unit (OU) in our Active Directory to store groups used to manage permissions.

First, we need to create the OU:

### <summary>
### Creates Web portal prerequires in Active Directory.
### </summary>
### <return>True on success, false otherwise</return>
function Configure-ADWebPortal()
{
    trap {
        Display-Info $_.Exception.Message
        $bln = $false
        continue
    }
    $bln = $true
    $CONST_GLOBAL_GRP = 2
    $CONST_UNIV_GRP = 8
    Display-Info 'Creating WebPortal Organizational Unit...'
    $objOU = [ADSI]''
    $objOU = $objOU.Create('OrganizationalUnit', 'OU=WebPortal')
    $objOU.SetInfo()
    
    Create-Group $objOU 'AdmWebPortal' 'WebPortal Administrators' $CONST_UNIV_GRP
    
    return $bln
}

Configure-ADWebPortal function creates an OU and a group in the new container.

The function uses an other one to create the Active Directory group. You can find the source code here:

### <summary>
### Creates an Active Directory group.
### </summary>
### <param name ="objOU">The container (ADSI object)</param>
### <param name ="strName">Group's name</param>
### <param name ="strDescription">Group's description</param>
### <param name ="intGroupType">Group's type</param>
function Create-Group($objOU, $strName, $strDescription, $intGroupType)
{
    trap {
        Display-Error $_.Exception.Message
        continue
    }
    Display-Info "Creating group $strName..."
    $objGroup = $objOU.Create('Group', "CN=$strName")
    $objGroup.Put('SamAccountName', "$strName")
    $objGroup.Put('Description', "$strDescription")
    $objGroup.Put('GroupType', $intGroupType)
    $objGroup.SetInfo()
}

To log errors and warnings, we call our dedicated functions.

In the example, the created group type is Universal. Why ? Well, maybe it will be use in a couple of days, maybe it will be a distribution group used by Exchange 2007... :)

That's fine, we successfully created Active Directory objects! And now ?

We will change on the fly the Active Directory and SQL database! In fact, the next step is to write a function to:

Get all OU with a specific name
Create a group in theses OU
Insert the OU name in the database calling a stored procedure!

### <summary>
### Synchronizes SQL database and Active Directory.
### </summary>
### <param name="objSQL">SQL connection object</param>
### <return>True on success, false otherwise</return>
function Synchronize-ADAndSQL($objSQL)
{
    trap {
        Display-Error $_.Exception.Message
        $bln = $false
        continue
    }
    $CST_GLB_GRP = 2
    $bln = $true
    $objEntry = [ADSI]''
    Clean-Database $objSQL
    foreach ($obj in $objEntry.psbase.Children) {
        if ($obj.Name.Value -match "^(\w+\d+)_(\w+)$") {
            $strFullName = $matches[0]
            $strCode = $matches[1]
            $strName = $matches[2]
            $strDN = $obj.psbase.Properties.DistinguishedName.Value
            Display-Info "OU $strFullName discovered"
            $strGroupName = "$strCode" + '_Administrators_WebPortal'
            Create-Group $obj "$strGroupName" "Admins for $strCode" $CST_GLB_GRP

            $objAdapter = New-Object Data.SqlClient.SqlDataAdapter
            $objAdapter.SelectCommand = New-Object Data.SqlClient.SqlCommand
            $objAdapter.SelectCommand.Connection = $objSQL
            $objAdapter.SelectCommand.CommandText = '[PR_ADDOU]'
            $objAdapter.SelectCommand.CommandType =
                [Data.CommandType]::StoredProcedure

            $objSqlParam = Build-SQLParam '@OUCode' $strCode
            [void]$objAdapter.SelectCommand.Parameters.Add($objSqlParam)
            $objSqlParam = Build-SQLParam '@OUName' $strName
            [void]$objAdapter.SelectCommand.Parameters.Add($objSqlParam)
            $objSqlParam = Build-SQLParam '@OUDN' $strDN

            $objAdapter.SelectCommand.ExecuteNonQuery() | Out-Null
        }
    }
    
    return $bln
}

OU name is divided in 2 parts: a code and the OU name joined by the '_' character. The stored procedure named PR_ADDOU has 2 parameters for theses 2 parts of the OU name. Executing a stored procedure is a good deal to separate PowerShell script and SQL traitment!

This solution Accelerator is just an example but we have seen a practical case of information system automation!

IIS automation

2009-05-27T16:29:00.002+02:00

Previous part of this post is HERE !

After having deployed the SQL database on which our Web portal is based on, we are going to deploy the web site... Using the second menu:

... We are discovering the GUI dedicated to the Web site deployment:

As the previous one, GUI is very simple. Four information are needed to deploy the Web Site:

Web server name,
Listening port,
Path to the Web Site source,
Credentials used by the application pool.

First fields are automatically filled and can be modifiable.

Let's see the PowerShell code !

First, we need to check that all specified information are correct:

### <summary>
### Checks the Web part parameters.
### </summary>
### <return>True if parameters are correct, false otherwise</return>
function Check-WebParameters()
{
    $bln = $false
        
    $bln = ($TxtWebServer.Text.Length -gt 0) -and
           ($TxtWebPort.Text.Length -gt 0) -and
           ($TxtWebPath.Text.Length -gt 0) -and
           ($TxtWebLogin.Text.Length -gt 0) -and
           ($TxtWebPassword.Text.Length -gt 0)
    if ($bln) {
        $bln = ($TxtWebServer.Text -match "^\w[\w\d-_]*$") -or
               ($TxtWebServer.Text -match "^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")
        if ($bln -eq $false) {
            Display-error 'Specified server name is invalid'
        } else {
            $bln = ($TxtWebPort.Text -match "^\d{1,5}$")
            if ($bln -eq $false) {
                Display-error 'Specified port is invalid'
            } else {
                $bln = Test-Path $TxtWebPath.Text
                if ($bln -eq $false) {
                    Display-error 'Specified Web folder is invalid'
                } else {
                    $strLogin = $TxtWebLogin.Text
                    if ($strLogin.Contains('\')) {
                        $strLogin = $strLogin.Split('\')[1]
                    }
                    $objUser = SearchOne-InDomain '' "(samaccountname=$strLogin)"
                    if ($objUser -eq $null) {
                        Display-error 'Specified user doesn''t exist in the domain'
                        $bln = $false
                    }
                }
            }
        }
    } else {
        Display-error 'All fields are required'
    }
    
    return $bln
}

Check-WebParameters function checks:

Web server name or IP address using a regular expression,
Listening port (a number up to 5 digits),
Existence of the user account used by the application pool. SearchOne-InDomain function makes the job:

### <summary>
### Searchs one object in an Active Directory container.
### </summary>
### <param name ="domainName">The container</param>
### <param name ="filter">LDAP filter</param>
### <param name ="scope">The scope for the research (optional)</param>
### <returns>Active Directory object</returns>
function SearchOne-InDomain($container, $filter,
                            $scope = [DirectoryServices.SearchScope]::Subtree)
{
    trap { return $null }
    $entry = New-Object DirectoryServices.DirectoryEntry("$container")
    $searcher = New-Object DirectoryServices.DirectorySearcher($entry)

    $searcher.Filter = $filter
    $searcher.SearchScope = $scope
    $searcher.FindOne()
}

We have already seen all this stuff !

Well, after having checked all information we can deploy our Web Site !

### <summary>
### Installs the IIS website.
### </summary>
function Deploy-WebServer()
{
    $bln = Check-WebParameters
    
    if ($bln -eq $false) { return }
    $bln = Copy-Source
    if ($bln -eq $false) { return }
    $LblError.Text = ''
    $strServer = $TxtWebServer.Text
    $strPath = $TxtWebPath.Text
    $strWebSiteName = 'Provisioning'
    $objLocator = New-Object -com WbemScripting.SWbemLocator
    $objProvider = $objLocator.ConnectServer($strServer, 'root/MicrosoftIISv2')
    $objService = $objProvider.Get("IIsWebService='W3SVC'")
    $objBindings = @($objProvider.Get('ServerBinding').SpawnInstance_())
    $objBindings[0].Properties_.Item('Port').value = $TxtWebPort.Text
    $createNewSiteMethod = $objService.Methods_.Item('CreateNewSite')

    $objInParameters = $createNewSiteMethod.InParameters.SpawnInstance_()
    $objInParameters.Properties_.Item('PathOfRootVirtualDir').value = $strPath
    $objInParameters.Properties_.Item('ServerBindings').value = $objBindings
    $objInParameters.Properties_.Item('ServerComment').value = $strWebSiteName
    
    Display-Info "Creating new WebSite '$strWebSiteName'..."
    $objOutParameters = $objService.ExecMethod_("CreateNewSite", $objInParameters)
    Display-Info "WebSite '$strWebSiteName' created"
    $id = ''
    $objOutParameters.properties_ | % {
        $id = $_.Value -match "[^']'([^']+)'.*"
        if ($id) { $id = $matches[1] }
    }
    if ($id.ToUpper() -match "^W3SVC/\d+$") {
        Display-Info "Creating new Application Pool '$strWebSiteName'..."
        $bln = Create-ApplicationPool $strServer $strWebSiteName
        if ($bln) {
            Display-Info "Configuring Website '$strWebSiteName'"
            $objSite = [ADSI]"IIS://$strServer/$id/Root"
            $objSite.Put("DefaultDoc", "Default.aspx")
            $objSite.Put("AppPoolId", $strWebSiteName)
            $objsite.put("AuthFlags", 4)
            $objsite.Put("AppFriendlyName", $strWebSiteName)
            $objsite.Put("AccessFlags", 1)
            $objsite.Put("AccessRead", $true)
            $objsite.Put("AccessScript", $true)
            $objsite.Put("AccessExecute", $true)
            $objSite.SetInfo()
            if ((Get-ChildItem env:COMPUTERNAME).Value -eq $strServer) {
                Set-FrameWorkVersion $id
                Display-Info "WebSite '$strWebSiteName' successfully created"
            } else {
                Display-Info "WebSite '$strWebSiteName' successfully created. " +
                             "You need to manually set up the .Net 2 version"
            }
        } else {
            Display-Error "Error creating Application pool '$strWebSiteName'"
            Display-Info "WebSite '$strWebSiteName' has not been configured"
        }
    } else {
        Display-Error "Invalid WebSite ID ($id)"
        Display-Info "WebSite '$strWebSiteName' has not been configured"
    }
}

Deploy-WebSite function makes the job!

At the begining of the function, we used Copy-Source: it's a small function called to copy Web Site source files to the Web server destination folder. This function uses Copy-Item Cmdlet (nothing special!).

Then, we use ADSI to configure IIS! So, we can use this function to deploy a Web Site using IIS 6 and later version!

The function makes the following operations:

Web Site creation using a specific name and listening port,
Application pool creation using Create-ApplicationPool function:

### <summary>
### Creates the IIS application pool.
### </summary>
function Create-ApplicationPool($strServer, $strAppPoolName)
{
    trap [Exception] {
        Display-Info $_.Exception.Message
        $bln = $false
        continue
    }
    $bln = $false
    $objApp = [ADSI]"IIS://$strServer/W3SVC/AppPools/$strAppPoolName"
    if ($objApp.distinguishedname -eq $null) {
        $strDomain = ([ADSI]'').Name.Value
        $objApp = [ADSI]"IIS://$strServer/W3SVC/AppPools"
        $objPool = $objapp.Create("IIsApplicationPool", $strAppPoolName)
        $objPool.Put('AppPoolIdentityType', 3)
        $strLogin = $TxtWebLogin.Text
        if ($strLogin.Contains('\') -eq $false) {
            $TxtWebLogin.Text = "$strDomain\$strLogin"
            $TxtWebLogin.Refresh()
        } else {
            $strLogin = $strLogin.Split('\')[1]
        }
        Display-Info "Setting Application pool credentials to $strLogin..."
        $objPool.Put('WAMUserName', $TxtWebLogin.Text)
        $objPool.Put('WAMUserPass', $TxtWebPassword.Text)
        $objPool.SetInfo()
        Display-Info "Adding user $strLogin to group IIS_WPG..."
        $objGroup = [ADSI]"WinNT://$strServer/IIS_WPG"
        $objGroup.Add("WinNT://$strDomain/$strLogin")
        $bln = $true
    } else {
        Display-Info "Application pool '$strAppPoolName' already exists."
        $bln = $true
    }

    return $bln
}

This function also adds the specified user account used by the application pool to the local group IIS_WPG
Web Site configuration:
- Dafault web page configured to "Default.aspx"
- Application pool assignment
- Windows authentication configuration
- Permisssions configuration: Read and Execute permissions
.Net Framework version configuration. This step is available only if the machine running our Solution Accelerator is our Web server. Set-FrameworkVersion function configures the Web Site to use the version 2 of the .NET framework:

### <summary>
### Sets the .NET framework version for a given website.
### </summary>
### <param name="strID">Website ID</param>
function Set-FrameWorkVersion($strID)
{
    $strPath = (Get-ChildItem Env:windir).Value + '\Microsoft.NET\Framework\'

    $objDir = Get-ChildItem $strPath | where {
               ($_.GetType().ToString() -eq 'system.io.directoryinfo') -And
               ($_.name -match "^(v2.[\d\.]+)$")} | sort name
    if ($objDir -ne $null) {
        $strPath += $matches[1]
        $strPath += "\aspnet_regiis.exe"
        $objSI = New-Object System.Diagnostics.ProcessStartInfo
        $objSI.UseShellExecute = $false
        $objSI.FileName = $strPath
        $objSI.Arguments = "-s $strID/Root"
        $objSI.RedirectStandardOutput = $true
        $objP = [System.Diagnostics.Process]::Start($objSI)
        $objP.WaitForExit()
    }
}

aspnet_regiis.exe binary is executed here!

All warnings or errors are displayed at the bottom of the window!

Well, IIS automation is simple! I hope that was not boring :)

SQL database deployment automation

2009-05-25T12:21:00.003+02:00

Previous part is HERE.

Before deploying Web Portal, we have to set up the database: Which web portal haven't a database... ? :)

So, that's the first job of our Solution Accelerator. In the previous post, you have seen the graphical user interface: let's use it !

So, just click on the first menu to deploy database !

A new dedicated screen is displayed:

It is a very simple GUI!
SQL server name and instance name are the only require fields and all we need is to click on the OK button...

However, there is one thing we can do using this GUI: configuring the user account which will be use to deploy the database. This can be done on the top of the window: we can choose if you want to use windows authentication (current logged user) or an other account.

At the bottom of the window, there is an empty space... So, we won't just keep this space empty! In fact, this area is dedicated to log: all information, warnings, errors will be display here.

Each step, each traitment of the script is described and displayed in the log area. That's the Display-Info and Display-Error functions job:

### <summary>
### Adds a log.
### </summary>
### <param name="str">Message to add</param>
### <param name="strType">Message type</param>
function Log-Message($str, $strType)
{
    $strDate = [DateTime]::Now.ToString('G')
    $strType = $strType.ToUpper()
    $strLine = "[$strDate] $strType: $str"
    Write-Verbose $strLine
    $script:strLog += $strLine + "`r`n"
}

### <summary>
### Displays error message.
### </summary>
### <param name="str">Message to display</param>
function Display-Error($str)
{
    $LblInfo.Text = ''
    $LblError.Text = $str
    $LblError.Refresh()
    Log-Message $str 'Error'
}

### <summary>
### Display information message.
### </summary>
### <param name="str">Message to display</param>
function Display-Info($str)
{
    $LblInfo.Text = $str
    $LblInfo.Refresh()
    Log-Message $str 'Info'
}

All theses displayed messages are logged thanks to Log-Message function which adds a date to the message.
Well, logging is very helpful to debug !

Since we saw the GUI and we have all prerequires we need: SQL scripts which will be executed, let's see the most interesting part: How to deploy the database using PowerShell!

First, we have to check that we can access to the SQL scripts.
We declare some variables in the script scope:

### <summary>
### Path to current script.
### </summary>
$script:strPath = $MyInvocation.MyCommand.Path

### <summary>
### SQL scripts to execute during installation step.
### Order is essential.
### </summary>
$script:arrSQLGenerateDBScripts = 'CreateDatabase.sql',
                                  'ProvisioningDatabase.sql'
### <summary>
### Installation logs.
### </summary>
$script:strLog = ''

We used the $MyInvocation PowerShell builtin variable to get our last executed command line: usefull to get the full path where the script is located!

arrSQLGenerateDBScripts variable contains an ordered list of SQL scripts to execute.

Then, strLog variable is a simple string which is our log.

The first thing to do is to check the SQL scripts access:

### <summary>
### Checks SQL files.
### </summary>
### <return>True on success, false otherwise</return>
function Check-SQLFiles()
{
    trap {
        $blnRes = $false
        continue
    }
    $tab = $script:strPath.Split('\')
    $strPath = ''
    for ($i = 0; $i -lt $tab.length - 2; $i++) {
        $strPath += $tab[$i] + '\'
    }
    $blnRes = $true
    $bln = $true
    Display-Info "Checking files in $strPath..."
    if ($script:arrSQLGenerateDBScripts.Length -gt 0) {
        foreach ($strFile in $script:arrSQLGenerateDBScripts) {
            $bln = Test-Path "$strPath\Database\$strFile"
            if ($bln -eq $false) { break }
        }
        $blnRes = $blnRes -and $bln
    }
    if ($blnRes) {
        Display-Info "Installation files successfully checked"
    } else {
        Display-Error "Installation files missing."
    }
    
    return $blnRes
}

This function checks that scripts' names stored in the script variable exist and are located in the ../Database folder.

Now, it's time to execute the SQL scripts!
We have to connect to the SQL database using a connection string:

### <summary>
### Generate the SQL connection string.
### </summary>
### <param name="strDB">Database name</param>
### <return>SQL connection string</return>
function Generate-StringConnection($strDB)
{
    $strInstance = $TxtDBServer.Text
    if ($TxtDBInstance.Text.Length -gt 0) {
        $strInstance += '\' + $TxtDBInstance.Text
    }
    $strInstance = $strInstance.ToUpper()
    $objBuilder = New-Object System.Data.SqlClient.SqlConnectionStringBuilder
    $objBuilder['Application Name'] = 'Web Portal'
    $objBuilder['Data Source'] = $strInstance
    $objBuilder['Initial Catalog'] = $strDB

    if ($ChkWindowsAuth.Checked -eq $false) {
        $objBuilder['User Id'] = $TxtLogin.Text
        $objBuilder['Password'] = $TxtPassword.Text
    } else {
        $objBuilder['Integrated Security'] = $true
    }

    return $objBuilder.ConnectionString
}

This function needs a database's name which will be used by the "Initial Catalog" parameter of the connection string.
If no SQL instance's name is provided, the server's name is used (default instance).

Then, we can write the function to execute the SQL scripts:

### <summary>
### Executes a SQL script.
### </summary>
### <param name="strScript">Script full name</param>
### <param name="objSQL">SQL connection</param>
### <return>True on success, false otherwise</return>
function Execute-SQLScript($objSQL, $strScript)
{
    trap {
        Display-Error $_.Exception.Message
        $bln = $false
        continue
    }
    $bln = Test-Path $strScript
    if ($bln) {
        Display-Info "Executing script $strScript..."
        $objSQLCmd = New-Object System.Data.SqlClient.SqlCommand
        $objSQLCmd.Connection = $objSQL
        $strContent = ''
        foreach ($strLine in Get-Content $strScript) {
            if ($bln -eq $false) { return $bln }
            if ($strLine.ToUpper() -match "^\s*GO\s*$") {
                $objSQLCmd.CommandText = $strContent
                $objSQLCmd.ExecuteNonQuery() | Out-Null
                $strContent = ''
            } else {
                $strContent += $strLine + "`r`n"
            }
        }
    } else {
        $LblError.Text = "File $strScript not found"
    }
    
    return $bln
}

There are more than one method to execute a SQL script. Here, we read the SQL script file line per line and execute the SQL request if we find the "GO" instruction.

Oh ! That's a chance to explain some regular expression basis !

"^\s*GO\s*$" string means that we search a string containing a GO surrounded by spaces (or not)!

Because it is relevant to know if the function has successfully executed the script, it returns a boolean :)

Well, at this point we have all elements to deploy the database:

### <summary>
### Installs the SQL database.
### </summary>
function Install-Database()
{
    trap {
        Display-Error $_.Exception.Message
        if (($objSQL -ne $null) -and
            ($objSQL.State -eq [Data.ConnectionState]::Open)) {
            $objSQL.Close()
        }
        $bln = $false
        continue
    }
    $LblError.Text = ''
    $objSQL = New-Object System.Data.SqlClient.SqlConnection
    $objSQL.ConnectionString = Generate-StringConnection 'master'
    Display-Info "Opening database connection..."
    $objSQL.Open()
    if ($objSQL.State -eq [Data.ConnectionState]::Open) {
        $strPath = Get-SQLScriptPath
        foreach ($strScript in $script:arrSQLGenerateDBScripts) {
            $bln = Execute-SQLScript $objSQL "$strPath\$strScript"
            if ($bln -eq $false) { break }
        }
        $objSQL.Close()
        Display-Info "Database connection closed"
        if ($bln) {
            Display-Info "Database successfully installed"
        } else {
            Display-Error "Error executing script $strPath\$strScript."
            Display-Info "Database installation aborted"
        }
    }
}

This function uses the previously detailed functions and deploy the database in few steps:

Connection string creation
Database connection opening
SQL script execution
Database connection closing

All theses steps are described in the log area of the window.

Next step is to deploy our Web Portal: IIS Automation !
See you soon.

Web portal deployment automation

2009-05-15T13:15:00.001+02:00

Web Portal deployment is not really easy. You have to check all prerequires, deploy source, check permissions, configure, and more...!

Here, just one simple thing will be done : Deploy a web portal using a single button : a pretty one !

So, I propose to make a kind of Solution Accelerator !

Let's see the graphical user interface (GUI)...

GUI is very simple, that's the goal ! It brings to light differents steps which will be detailed in the following posts:

SQL database deployment (SQL script execution)
Web portal deployment (IIS automation)
Web portal configuration (Acive Directory, universe... interaction)

So, the only thing to do rigth now is to launch our PowerShell session!

See you soon for the first step!

PowerShell 2 & OpenXML: Generate a server form

2009-05-14T09:36:00.001+02:00

That's it, now we can generate a server form in 4 steps :

Part 1 : Prerequires installation and configuration.
Part 2 : PowerShell module creation collecting software and hardware data from a remote machine.
Part 3 : Word 2007 template creation.
Part 4 : Server form generation.

See you soon for the next article !

Create a server form with PowerShell 2 & Word 2007 (Part 4)

2009-05-10T02:24:00.003+02:00

Previous part of this article is HERE !

This is the last part. We will be able to generate server form using PowerShell !

All we have to do is to write some functions to update our Word document.

function Set-OpenXmlText($objNode, $objNsMgr, $strData)
{
    $blnIsCheckBox = $false
    $objNodeT = $null
    $objNodeR = $null

    $objNodeTmp = $objNode.SelectSingleNode('w:tc', $objNsMgr)
    if ($objNodeTmp -ne $null) { $objNode = $objNodeTmp }
    $objNodeTmp = $objNode.SelectSingleNode('w:p', $objNsMgr)
    if ($objNodeTmp -ne $null) { $objNode = $objNodeTmp }
    $objNodes = $objNode.SelectNodes('w:r', $objNsMgr)
    foreach ($objNodeR in $objNodes) {
        $objNodeSYM = $objNodeR.SelectSingleNode('w:sym', $objNsMgr)
        $blnIsCheckBox = $objNodeSYM -ne $null
        if ($blnIsCheckBox) {
            $objAttr = $objNodeSYM.Attributes |
                       where-Object { $_.Name -eq 'w:char'}
            $objAttr.Value = 'F0A8'
            if ($strData -eq $true) { $objAttr.Value = '00FE' }
            break
        }
        $objNodeT = $objNodeR.SelectSingleNode('w:t', $objNsMgr)
        if ($objNodeT -ne $null) { $objNodeT.InnerText = '' }
    }
    if ((-not $blnIsCheckBox) -And ($objNodeT -ne $null)) {
        $objNodeT.InnerText = $strData
    }
}

We won't go inside the OpenXML format however we will need an overview and some basis to understand Set-OpenXmlText function. Nothing complex, don't worry !

The first thing we need is to understand what's happen when a content control is inserted:

When we change the content of the Word document, we change the file /word/document.xml in the DOCX package. In fact, we add the following tags:

The content control tag is w:sdt which is divided into two parts (green et red color on the image).

Green part (w:sdtPr tag) gathers all content control properties : by example, its name. In the example, the content control name is FctNetworkInfrastructure. This name is get by Get-OpenXmlContentCtrlAlias function which is detailed in the previous article!

Set-OpenXmlText function will change the blue part (w:sdtContent tag) which is the content of the content control!

That's all !

Create a server form with PowerShell 2 & Word 2007 (Part 3)

2009-05-09T19:20:00.001+02:00

Previous part of this post is HERE !

Now we get remote server information, we can create our Word 2007 template by hand. By hand ? Why ? Because our script will refresh some parts of this document. So, the script will be independant of the template and we will be able to created a template with our company logo and colors.

PowerShell will write in parts of the document. Theses parts will be called Content Control ! We can insert a content control in the Word 2007 « developer » tab and the « Controls » group:

For each information we get in the previous post (using our PowerShell module), we will insert a content control in our document.

When a content control is inserted, we can specify a name. Our PowerShell script will be able to choose the part of the document to complete matching names of content controls and object properties names.

In the previous part of this post, we wrote some functions: Get-ComputerHardware and Get-ComputerSoftware. Theses functions return a custom object: each property is an information extracted from the remote computer.

The tips is to use the same name for content controls and object properties.

After having created the document with our company's colors and inserted content controls... We have to write the script to refresh the document which means write into content control !

To do that, in a new file named « Generate-ServerForm.ps1 », write the following function:

function Refresh-OpenXmlDocument($strDocPath, $strComputer)
{
    $objDoc = Get-OpenXmlDocument -Path $strDocPath -SuppressBackups
    if ($objDoc -eq $null) { return }

    $objUri = New-Object Uri('/word/document.xml', [UriKind]::Relative)
    $objPart = $objDoc.Package.GetPart($objUri)

    $script:objXmlDoc = New-Object Xml.XmlDocument
    $script:objXmlDoc.Load($objPart.GetStream())

    $objNsMgr = New-Object Xml.XmlNamespaceManager($objXmlDoc.NameTable)
    $strURL = 'http://schemas.openxmlformats.org'
    $objNsMgr.AddNamespace('w', "$strURL/wordprocessingml/2006/main")

    $objNodes = $script:objXmlDoc.DocumentElement.GetElementsByTagName('w:sdt')
    $objInfo = Get-ComputerInfo $strComputer

    foreach ($objNode in $objNodes) {
        $objN = $objNode.SelectSingleNode('w:sdtPr', $objNsMgr)
        $strAlias = Get-OpenXmlContentCtrlAlias $objN $objNsMgr
        if ($strAlias -ne '') {
            $objProperty = $objInfo | Get-Member -Name $strAlias
            if ($objProperty -ne $null) {
                $objN = $objNode.SelectSingleNode('w:sdtContent', $objNsMgr)
                switch -regex ($objInfo.$strAlias.GetType().Name) {
                    '\[\]$' {
                        Set-OpenXmlTable $objN $objNsMgr $objInfo.$strAlias
                    }
                    default {
                        Set-OpenXmlText $objN $objNsMgr $objInfo.$strAlias
                    }
                }
            }
        }
    }

    $script:objXmlDoc.Save($objPart.GetStream())
    $objDoc.Close()
}

It's time to analyse the function !

The main goal is to write into content controlsof the Word document. This function uses 2 parameters :

Full path to the Word document (template)
Remote server name : our server form will gather information about this server

For now, let's go inside the OpenXML format: don't be afraid, that's an easy part !

First, have a look to the Get-OpenXMLDocument Cmdlet. It comes from PowerTools. So, to use it you have to install theses tools as described in this post!

As an introduction to the OpenXML format: since Office 2007, documents are ased on an opened format (XML) and compressed in a ZIP archive. In fact, if you renamed a DOCX file into a ZIP file you can decompress it!

Using Word 2007, you will have a « /word/document.xml » file used to store the main content of the Word document. It is this file we will modify searching the « w:sdt » tag which is a content control!

$script:objXmlDoc.DocumentElement.GetElementsByTagName('w:sdt')

here we used $script:objXmlDoc so we can access to this variable all over the script.

We can jump from a content control to an other just searching the specified tag! Then, for each tag found, we have to get its name which is also the name of the custom object property previously built by Get-ComputerInfo. This last function merges objects built by Get-ComputerHardware and Get-ComputerSoftware functions.

To do that, you can add the following code to the PowerShell module:

function Merge-Object($objSource, $objDest)
{
    $objSource | Get-Member -MemberType NoteProperty | % {
        Add-Property $objDest $_.Name $objSource.($_.Name)
    }
    
    return $objDest
}

function Get-ComputerInfo($strComputer)
{
    $objHardware = Get-ComputerHardware $strComputer
    $objSoftware = Get-ComputerSoftware $strComputer
    
    return (Merge-Object $objHardware $objSoftware)
}

Merge-Objet function merges customized objects.

Don't forget to export our new function:

Export-ModuleMember -Function 'Get-ComputerHardware',
                              'Get-ComputerSoftware',
                              'Get-ComputerInfo'

Well, we need one more thing: our script have to use our module! This can be done using Import-Module Cmdlet. So, our script have to start with the following command:

Import-Module .\Computer_Info.psm1

Here, our module is located in the script directory.

Finally, for each content control, we gets its name using Get-OpenXmlContentCtrlAlias function:

function Get-OpenXmlContentCtrlAlias($objNode, $objNsMgr)
{
    $strAlias = ''

    $objNode = $objNode.SelectSingleNode('w:alias', $objNsMgr)
    $strAlias = $objNode.Attributes | where-Object { $_.Name -eq 'w:val'}
    if ($strAlias -ne $null) { $strAlias = $strAlias.Value }
    else { $strAlias = '' }
    
    return $strAlias.Trim()
}

There are two cases: if we have to write information in a table then Set-OpenXmlTable is called else Set-OpenXmlText is called!

Since we done a lot of works, it's time to have a break!
See you soon!

Create a server form with PowerShell 2 & Word 2007 (Part 2)

2009-05-08T17:15:00.001+02:00

Previous part of this post is HERE !

This is the first step : selecting and getting information about servers !

In this post we wiil create a PowerShell module which will gather all information from our servers. But... What is a module ? It's just a set of functions, a library we will reuse and share !

Modules are only available with PowerShell 2.0.

First, we have to create a file named « Computer_Info.psm1 ». File extension is .PSM1 and not .PS1 !
Then we can write our functions into the file. Theses functions will get information we need on our servers.

The PowerShell script which will generate the Word 2007 report will call functions from this module. The goal is to capitalize !

By default, PowerShell searches modules in folders listed in the environment variable PSMODULEPATH and in the working directory. To display the variable use the command:

PS> $env:PSMODULEPATH

Now we can start to get information from our servers. For this job, we will use more than one method. The first one is WMI !

The following function (the first one in our module) is just an abstract layer for the PowerShell Cmdlet Get-WmiObject. Just to make the code easier to read... :)

function Get-WmiInfo($strClass, $strComputer)
{
    return Get-WmiObject -Class $strClass -Namespace 'root\cimv2' `
                         -ComputerName $strComputer
}

We will add an other "tool function":

function Add-Property($obj, $strProperty, $objValue)
{
    Add-Member -InputObject $obj -Type 'NoteProperty' -Name $strProperty `
               -value $objValue -force
}

Add-Property function is an abstract layer for the PowerShell Cmdlet Add-Member : here, the function adds a simple property to an object.

So, now we can do the main traitment: gather all information we need !
The following function gets hardware information from servers:

function Get-ComputerHardware($strComputer)
{
    $objRes = New-Object Object
    $int = 0
    
    # Processors
    $obj = Get-WmiInfo 'Win32_Processor' $strComputer
    foreach ($objInfo in $obj) {
        Add-Property $objRes 'Is32Bit' ($objInfo.Architecture -eq 0x0)
        Add-Property $objRes 'Is64Bit' ($objInfo.Architecture -eq 0x9)
        $int++
    }
    Add-Property $objRes 'NbCPU' $int
    
    # BIOS
    $obj = Get-WmiInfo 'Win32_Bios' $strComputer
    Add-Property $objRes 'BIOS' $obj.Name
    
    # System
    $obj = Get-WmiInfo 'Win32_ComputerSystem' $strComputer
    $int = [int]($obj.TotalPhysicalMemory / 1024 / 1024 / 1024)
    Add-Property $objRes 'TotalMemory' "$int Go"
    Add-Property $objRes 'Manufacturer' $obj.Manufacturer
    Add-Property $objRes 'Model' $obj.Model
    Add-Property $objRes 'Domain' $obj.Domain
    Add-Property $objRes 'DNSName' ($obj.Name + '.' + $obj.Domain)
    Add-Property $objRes 'NetBIOSName' $obj.Name
    
    # Media
    $obj = Get-WmiInfo 'Win32_CDROMDrive' $strComputer
    foreach ($objInfo in $obj) {
        switch ($objInfo.MediaType)
        {
            'CD-ROM' { Add-Property $objRes 'MediaCD' $true }
            'DVD-ROM' { Add-Property $objRes 'MediaDVD' $true }
            'CD Writer' { Add-Property $objRes 'MediaCDRW' $true }
            'DVD Writer' { Add-Property $objRes 'MediaDVDRW' $true }
            default { }
        }
    }
    
    # Physical or virtual
    $obj = Get-WmiInfo 'Win32_BaseBoard' $strComputer
    $bln = ($obj.Manufacturer.Tolower() -contains 'microsoft') -Or
           ($obj.Manufacturer.Tolower() -contains 'vmware')
    Add-Property $objRes 'IsVirtual' $bln
    Add-Property $objRes 'IsPhysical' (-not $bln)
    
    # Network adapters
    Set-StrictMode -Off
    $obj = Get-WmiInfo 'Win32_NetworkAdapter' $strComputer |
           Where-Object { $_.PhysicalAdapter -eq $true } |
           Select-Object ProductName, MACAddress
    Set-StrictMode -Version 2.0
    Add-Property $objRes 'NetworkCards' $obj
    
    # Disks
    $obj = Get-WmiInfo 'Win32_DiskDrive' $strComputer |
           Select-Object Model, Size
    Add-Property $objRes 'Disks' $obj
    
    # Volumes
    $obj = Get-WmiInfo 'Win32_LogicalDisk' $strComputer |
           Where-Object { $_.DriveType -eq 3 } |
           Select-Object VolumeName, DeviceID, Size, FreeSpace
    Add-Property $objRes 'Volumes' $obj

    return $objRes
}

Get-ComputerHardware function returns a customized object. Each property of the object is an information about server's hardware.

For softwares:

function Get-ComputerSoftware($strComputer)
{
    $objRes = New-Object Object
    
    # Operating system
    $obj = Get-WmiInfo 'Win32_OperatingSystem' $strComputer
    Add-Property $objRes 'OSName' $Obj.Caption
    Add-Property $objRes 'OSVersion' $Obj.Version
    Add-Property $objRes 'OSServicePack' $obj.CSDVersion
    Add-Property $objRes 'OSArchitecture' $obj.OSArchitecture
    
    # Services
    $obj = Get-Service -ComputerName $strComputer |
           Select-Object DisplayName, ServiceName, Status
    Add-Property $objRes 'Services' $Obj
    
    # KB
    $obj = Get-WmiInfo 'Win32_QuickFixEngineering' $strComputer |
           Sort-Object InstalledOn |
           Select-Object Description, HotFixID, InstalledBy, InstalledOn
    Add-Property $objRes 'KB' $Obj
    
    return $objRes
}

Here we use the Get-Service Cmdlet with –ComputerName parameter which has been added in PowerShell V2 !

At this point, our module is not yet usable !

In our module, we wrote some functions used only by function which get software and hardware information. We want that only the two main functions of the module are usable because use the tools function out of context could be a bad idea...

Export-ModuleMember -Function 'Get-ComputerHardware',
                              'Get-ComputerSoftware'

Export-ModuleMember Cmdlet exposes only specified functions. So, only our main functions will be usable with our module !

In this post we have:
1. Created PowerShell 2 module,
2. Get hardware and software information from a remote computer.

In the next post, we will create our Word 2007 document which will use to generate our server form !

Create a server form with PowerShell 2 & Word 2007 (Part 1)

2009-05-07T20:32:00.001+02:00

What if it was possible to get pertinent informations about all our Windows servers and generate a detailed report and then send it by mail to our manager monthly ?

We will have more time for cofee ? sure... Or maybe we will have more time to enhances the efficiency of our production processes !

Well, in this post splited into 4 parts, we will do the job !

We need 2 things :
1. PowerShell V2 : of course ! :)
2. OpenXML SDK 1.0 : library used to work with DOCX format (OpenXML).

If you didn't install PowerShell V2, go to this post ! Else, just download OpenXML SDK 1.0 and install it.

You have to know that Cmdlets (powerShell commands) exist to work with OpenXML format. Theses Cmdlets will make easier our job : PowerTools (Open source project developed using C#).

To install PowerTools, you will need to download the source code and then compile it using Visual C# Express (the free edition :)) to build the DLL which contain Cmdlets. Or you can download the DLL from here...

Then, you have to do in a PowerShell session :

PS> cd C:\Windows\Microsoft.NET\Framework64\v2.0.50727
PS> .\InstallUtil.exe C:\OpenXml.PowerTools.dll       
PS> Add-PSSnapin OpenXml.PowerTools

Installutil.exe is located in the .Net 2 Framework folder. In the previous example: « C:\Windows\Microsoft.NET\Framework64\v2.0.50727». The POwerTools DLL is located in C: root folder.

Since we have all the prerequires we can do the job : Generate a Word 2007 document !
This work is divided into 3 parts:

1. Selecting and getting pertinent information from our servers,
2. Creating a Word 2007 template for the report,
3. Report creation.

Each step will be detailed in a post to preserve the suspense... ok sorry... :)

See you soon for the first step !
Until then, check that you installed all the prerequires !

PowerShell 2.0: Introduction

2009-05-06T21:20:00.001+02:00

PowerShell is a command line tool used to manage Windows based computers. Ok, that's a beautiful theoretical definition...

Theory is good but practice is sometimes better ! So let's go !

Oh, just another thing ! For my first post, we will set up our environment to test our PowerShell script.

PowerShell current version is 1.0 however we will use PowerShell 2 ! (Which is actually in CTP3 version). This new version is just awesome : we will play with some cool features !

So, the first thing to do is to check prerequires !
Operating system version has to be at least Windows XP SP3 or Windows Server 2003 SP2. To use some PowerShell V2 features we need at least Windows Vista SP1 or Windows Server 2008.

Next, we have to uninstall PowerShell 1.0 if installed and download then install the following prerequires :
1. .NET Framework 2.0 : PowerShell is based on .NET Framework !
2. Framework .NET 3.5.1 : if we want to use PowerShell Integrated Script Environment (ISE)... And we want !
3. PowerShell V2 CTP3 : our command line tool and its editor (ISE) : all in one !
4. WinRM 2.0 CTP3 : for remoting ! Because it is cool to manage thousand of computers from the sofa...

After having installed theses components observing order we can start to play !

Well, maybe we have to configure some component in order to use the coolest feature of PowerShell V2 : remote management using WinRM 2.0 !

WinRM is an implementation of WS-Management protocol by Microsoft. It is used to manage computer using HTTP as transport protocol (which can be secured with HTTPS).

In fact, WinRM is a Windows service installed on the computer : we have to start it before using PowerShell V2 remote management features.

So, in a PowerShell session running as local Administrator, execute the following command to start WinRM service :

PS> Start-Service WinRM

Now, we can use the PowerShell V2 WinRM provider to configure the remote management.

PowerShell V2 is a client and a server. In other terms, we need PowerShell V2 installed and configured on the local machine and the remote machine !

Well, stop talking and let's configure the port used to listen requests and the protocol to use :

PS> cd WSMan:\localhost\Listener                          
PS> New-Item –Path . –Address * -Transport HTTP –Port 8080

PowerShell will use HTTP as transport protocol, the port 8080 and will listen on all interfaces. If an other application uses the same port (as a web server) there is no problem because WinRM shares the port.

This configuration has to be done on all managed computers.

Now, we are ready to start playing with our tool.
You will discover PowerShell V2 across posts on this blog and how to use it in your production environment.

See you soon !

Welcome

2009-05-04T21:26:00.001+02:00

Hello and welcome on this blog dedicated to the process oriented and best practises PowerShell development. You will find information on ITIL best practices associated with Microsoft technologies and ideas to deploy automated IT operations, this information will be based on the following:

Microsoft Operations Framework (MOF)
Microsoft PowerShell
Microsoft Operational guides

This blog is primarily intended for architects, administrators, and system engineers wishing to find information and simple solutions to optimize and streamline their technical operations recurring infrastructure management Microsoft.

Good Reading

Mouloud