Scripting Window Server AppFabric Configuration

Article
05/20/2010

Windows PowerShell cmdlets are an administration-focused scripting language that helps you achieve control and productivity when managing your Windows Server AppFabric installation. There are cmdlets particular to AppFabric and those that are generic in nature. The output results of one cmdlet can be piped to another cmdlet by combining the two statements with a single command and the “|” operator. You can invoke Windows PowerShell cmdlets either interactively using the Windows PowerShell console or through scripts. This brings the power of the .NET Framework to command-line users as well as script writers. Just like the IIS interface, the AppFabric cmdlets can be used to manage remote services and applications.

As an administrator you may want to create scripts for specific core tasks. This saves time with duties that are done on a repetitive basis. It also makes the process less error prone since each time you will be running the same script file time through that task.

A commonly scripted task that you may want to manage through cmdlets is the AppFabric configuration process. We will now examine some core configuration operations that you can script for AppFabric to function correctly after the installation. Before running these cmdlets, the following steps in the installation process must complete in order to properly configure AppFabric using scripting.

Databases have been prepared using the Initialize-ASMonitoringDatabase and Initialize-ASPersistenceSqlDatabase cmdlets. There may be permissions issues that need to be addressed before this will work that are particular to the security requirements at your installation.
The users of the Administrator role must have logon as a service privileges because they will be used to run the Event Collection and Workflow Management services.
The identity of the application pool used to run AppFabric applications must be a member of the logical AppFabric Users role.
The application pool must be a .NET Framework 4 application pool.

Note that in this article we will not discuss installing, configuring, and securing AppFabric on a domain or across a Web farm.

CMDLET/CMD OPERATION	ACTION
NET LOCALGROUP	Add the AppFabric Administrator user to the local Administrators group. NET LocalGroup is a command line executable. One example is: net localgroup Administrators /Add testuser
Get-WmiObject	Set the Event Collection Service and Workflow Management Service identities. Get-WmiObject is a command line executable.
AppCmd	Add connection strings to the connection strings section in root web.config. AppCmd is a command line executable and used for configuring AppPool Identity with AppCmd. appcmd set config /section:applicationPools /[name='Marketing'].processModel.identityType:SpecificUser /[name='Marketing'].processModel.userName: Marketer /[name='Marketing'].processModel.password: M@dr1d$P
AppCmd	Set the default AppPool identity.
Initialize-ASPersistenceSqlDatabase	Creates and initializes a SQL Server persistence database on the specified database server if the specified database does not already exist on the server. The initialization process creates persistence-related artifacts (tables, views, stored procedures, and so on). If the database already exists on the server, the cmdlet initializes the database with the persistence artifacts. The cmdlet also adds any specified Windows groups to corresponding SQL Server roles.
Initialize-ASMonitoringSqlDatabase	Creates and initializes a SQL Server monitoring database on the specified database server if the specified database does not already exist on the server. The initialization process creates monitoring-related artifacts (tables, views, stored procedures, and so on). If the database already exists on the server, the cmdlet initializes the database with the monitoring artifacts. The cmdlet also adds any specified Windows groups to corresponding SQL Server roles.
Set-ASAppMonitoring	Enables monitoring and specifies the connection string that will be used to connect to the SQL Server monitoring database,
Set-ASAppSqlServicePersistence	Enables SQL Server persistence, specifies the connection string that will be used to connect to the SQL Server persistence database, and sets advanced persistence related parameters at the specified level.

These cmdlets can be run individually, or put inside a script file with a .ps1 extension to run as a Windows PowerShell Script. Here is an example of a script to assist in configuration of AppFabric. The script has four functions and three sections. Its main goals of this script are to get the user to enter a user name and password, change the logon user and password for a specified service, generate a SQL connection string to a specific database, and to add that connection string to the root Web.config file. To run these commands, load PowerShell and then load the ApplicationServer module using command (in PowerShell) Import-Module ApplicationServer.

    1: ############################################################
    2: # PowerShell script to configure
    3: # Application Server Extensions for .NET 4
    4: # Copyright (c) Microsoft Corporation.  All rights reserved.
    5: ############################################################
    6: if ((Get-Command -Module ApplicationServer) -eq $null)
    7: {
    8:     Import-Module ApplicationServer # Application Server Extensions for .NET 4
    9: }
   10:  
   11: ############################################################
   12: function GetUserCredential([string]$serviceName, [string]$serviceDescription, [string]$serviceUser)
   13: {
   14:     $credential = $host.ui.PromptForCredential($serviceName, $serviceDescription, $serviceUser, "")
   15:     return $credential # PSCredential object
   16: }
   17:  
   18: function SetServiceCredential([string]$serviceName, $credential)
   19: {
   20:     $domainAndUserName = $credential.GetNetworkCredential().Domain + "\" + $credential.GetNetworkCredential().UserName;
   21:     $service = Get-WmiObject Win32_Service -filter "name='$serviceName'"
   22:     $service.Change($null, $null, $null, $null, $null, $null, $domainAndUserName, $credential.GetNetworkCredential().Password) |out-null
   23:     Restart-Service -name "$serviceName"
   24: }
   25:  
   26: #### Gets a SQL connection string to the specified server and database.
   27: function GetSqlConnectionString([string]$server, [string]$database)
   28: {
   29:     $builder = New-Object System.Data.SqlClient.SqlConnectionStringBuilder
   30:     $builder.PSBase.DataSource = $server
   31:     $builder.PSBase.InitialCatalog = $database
   32:     $builder.PSBase.IntegratedSecurity = $true
   33:     return [string] $builder.ToString()
   34: }
   35:  
   36: #### Adds or updates the specified connection string setting in the specified .NET configuration file.
   37: function UpdateConnectionString([string]$name, [string]$connectionString, [string]$providerName)
   38: {  
   39:     &; $appcmd set config /clr:4 /commit:WEBROOT /section:connectionStrings /+"[connectionString='$connectionString',name='$name',providerName='$providerName']" |out-null
   40: }
   41:  
   42: ##############################
   43: ### User defined variables ###
   44: ### List of variables used in the script. You can modify these variables to customize the script to the specifics of the environment.
   45: ##############################
   46:  
   47: $computer = "."
   48: $appcmd = "$env:SystemRoot\system32\inetsrv\appcmd.exe"
   49:  
   50: ### Event Collector Service (ECS) and Workflow Management Service (WMS) service names.
   51: $ECS_ServiceName = "AppFabricEventCollectionService"
   52: $WMS_ServiceName = "AppFabricWorkflowManagementService"
   53:  
   54: ### Domain user, member of Application Server Administrators group.
   55: ### ECS and WMS will run under this identity.
   56: $systemService_Domain ="corp"
   57: $systemService_UserName = "dubAdmin"
   58:  
   59: ### Monitoring database
   60: $Monitoring_ConnectionStringName = "monitoringDB"
   61: $Monitoring_ConnectionString = GetSqlConnectionString "AD-SQL" "monitoringDB"
   62:  
   63: $Monitoring_MonitoringLevel = "HealthMonitoring" # Used by the monitoring behavior.
   64:  
   65: ### Persistence database
   66: $Persistence_ConnectionStringName = "persistenceDB"
   67: $Persistence_InstanceStoreName = "sqlPersistence"
   68: $Persistence_ConnectionString = GetSqlConnectionString "AD-SQL" "persistenceDB"
   69:  
   70: ###########################
   71: ### Collect credentials ###
   72: ### Calls the GetUserCredential function to obtain credentials from the user for use in the configuration of the system services (Workflow Management service and Event Collection service).
   73: ###########################
   74:  
   75: $systemService_Credentials = GetUserCredential "System Services" "Provide the credentials for the System Services user:" "$systemService_Domain\$systemService_UserName"
   76: $systemService_Domain = $systemService_Credentials.GetNetworkCredential().Domain
   77: $systemService_UserName = $systemService_Credentials.GetNetworkCredential().UserName
   78:  
   79: ############################
   80: ### Update configuration ###
   81: ### Apply the configuration based on the variables and the collected information
   82: ############################
   83:  
   84: ####Add the AppFabric Administrator user to the local Administrators group.
   85: Write-Output "Adding the Administrator user to the local Administrators group..."
   86: $oGroup = [ADSI]"WinNT://$computer/Administrators"
   87: trap { continue } #'Administrator user already a member of the local Administrators group...'; 
   88: & { $oGroup.Add("WinNT://$systemService_Domain/$systemService_UserName") }
   89:  
   90: ####Set Event Collection service configuration.
   91: Write-Output "Updating Event Collection service..."
   92: SetServiceCredential $ECS_ServiceName $systemService_Credentials
   93:  
   94: ####Set Workflow Management service configuration.
   95: Write-Output "Updating Workflow Management service..."
   96: SetServiceCredential $WMS_ServiceName $systemService_Credentials
   97:  
   98: ####Add connection strings to the connection strings section in root web.config.Write-Output "Creating connection strings..."
   99: UpdateConnectionString $Monitoring_ConnectionStringName $Monitoring_ConnectionString "System.Data.SqlClient" |out-null
  100: UpdateConnectionString $Persistence_ConnectionStringName $Persistence_ConnectionString "System.Data.SqlClient" |out-null
  101:  
  102: ####Create an Instance Store entry for the persistence connection string.
  103: Write-Output "Creating Persistence Instance Store..."
  104: Add-ASAppSqlInstanceStore -Name $Persistence_InstanceStoreName -ConnectionStringName $Persistence_ConnectionStringName -Root |out-null
  105:  
  106: ####Set the persistence and monitoring behavior.
  107: Write-Output "Creating default behaviors..." 
  108: Set-ASAppMonitoring -ConnectionStringName $Monitoring_ConnectionStringName -MonitoringLevel $Monitoring_MonitoringLevel -Root |out-null
  109: Set-ASAppSqlServicePersistence -ConnectionStringName $Persistence_ConnectionStringName -Root -HostLockRenewalPeriod "00:00:20" -InstanceEncodingOption "GZip" -InstanceCompletionAction "DeleteNothing" -InstanceLockedExceptionAction "BasicRetry" |out-null

Share via

Scripting Window Server AppFabric Configuration

Additional resources