Lesson 3: Configuring the Order Service with Windows PowerShell

Article
06/17/2011

Time to complete: 20 minutes

Objective: To demonstrate using the Windows Server AppFabric cmdlets to configure applications.

Purpose: The AppFabric cmdlets for Windows PowerShell represent a useful tool that developers and administrators can use to automate configuration and management of applications that include WCF and/or WF services. In this lesson you will reconfigure monitoring and persistence for the Order Service application.

Prerequisites

Note the following prerequisites before you begin this lesson:

You must have set up the Windows PowerShell session as documented in Lesson 1: Getting Started with Windows Server AppFabric Cmdlets for Windows PowerShell.
You must have deployed the Order Service application as documented in Lesson 2: Deploying the Order Service Application with Windows PowerShell.

Procedure

You will go through the following procedures to reconfigure the Order Service application with Windows PowerShell:

Create and initialize the monitoring and persistence stores for the application.
Create the connection strings for the store.
Configure the OrderWorkflow Service for the Order Service application to use the new monitoring and persistence store.
Enable the net.pipe protocol for the application.

Creating and Initializing the Monitoring and Persistence Databases

In this section you will create and initialize a new monitoring store and a new persistence store for use with the Order Service application.

Creating and initializing the monitoring store

Execute the following command from Windows PowerShell.
```
Initialize-ASMonitoringSqlDatabase -Database "OrderService_PS" -Admins "AS_Administrators","NT AUTHORITY\LOCAL SERVICE" -Readers "AS_Observers" -Writers "BUILTIN\IIS_IUSRS" | fl *
```
Notice that the store name you have given has a “_PS” suffix representing that you did this with Windows PowerShell. This is so you do not have any naming conflicts with the user interface tutorial.

The permissions you set for the store are based on default AppFabric permissions and principal names.

In the previous command you piped the resulting store object out to the fl alias for the Windows PowerShell Format-List cmdlet. It is easier to see the result of the operation by using the list format instead of the default table format because the default format truncates the result.

Verify that your output in Windows PowerShell after running this command looks similar to the following with no errors.

Server           : SERVER1
Database         : OrderService_PS
ConnectionString : Data Source=SERVER1;Initial Catalog=OrderService_PS;Integrated Security=True

A new monitoring store named OrderService_PS has now been created and initialized for monitoring.

Creating and initializing the persistence store

To initialize the OrderService_PS store with persistence-related tables and artifacts, you use the Initialize-ASPersistenceDatabase cmdlet. This cmdlet accepts three security-related parameters:

-Admins
-Readers
-Users

For this tutorial you are again using the default AppFabric principal names. When using these parameters with this cmdlet you must use the full principal names. To accomplish this you will use the environment provider for Windows PowerShell to resolve the local computer name. To see how this works, enter the following command into Windows PowerShell.

$env:COMPUTERNAME

The result of that command displays your local computer name according to the COMPUTERNAME environment variable. You will use this approach to provide the full principal name of the default AppFabric principals.

To create and initialize the persistence store for the Order Service application

Enter the following command in Windows PowerShell to initialize the OrderService_PS store for persistence using the default AppFabric principal names.
```
Initialize-ASPersistenceSqlDatabase -Database "OrderService_PS" -Admins "$($env:COMPUTERNAME)\AS_Administrators" -Readers "$($env:COMPUTERNAME)\AS_Observers" -Users "BUILTIN\IIS_IUSRS" –Confirm:$false | fl *
```
Notice the –Confirm:$false parameter you passed. This allows you to bypass prompts for confirming the changes to the store.

Verify that the result is similar to what is shown below with no errors.

Server           : SERVER1
Database         : OrderService_PS
ConnectionString : Data Source=SERVER1;Initial Catalog=OrderService_PS

The OrderService_PS store is now initialized for use with persistence.

Creating the Connection String

To configure the application to use the new monitoring and persistence store you just created, you must create a connection string for the new store. Presently the ApplicationServer module for Windows PowerShell does not include a cmdlet to do this. So we will use a script function example based on the sample code in the Scripted Configuration of AppFabric sample that shows how you can do this. For more information about this sample, see Samples.

To create the connection string for the new store

In Windows PowerShell type the following command to open Utility.ps1.
```
Notepad Utility.ps1
```

Copy and paste the following code at the bottom of the file in Notepad.

#=========================================================================================================#
#===                                                                                                   ===#
#=== Adds or updates the specified connection string setting in the specified .NET configuration file. ===#
#===                                                                                                   ===#
#=========================================================================================================#

function UpdateConnectionString([string]$name, [string]$connectionString)
{
    $providerName = "System.Data.SqlClient"

    $NETFramework4Path = gp -Path HKLM:\Software\Microsoft\'NET Framework Setup'\NDP\v4\Full
    $ConfigPath = "$($NETFramework4Path.InstallPath)Config\Web.config"

    Write-Output ("ConfigPath : " + $ConfigPath)

    $xml = [xml](Get-Content $ConfigPath)
    $root = $xml.get_DocumentElement()


    $connectionStrings = $root.SelectSingleNode("connectionStrings")
    if ($connectionStrings -eq $null)
    {
        $locations = $root.SelectNodes("location")

        foreach ($locationNode in $locations)
        {
            $locStrings = $locationNode.SelectSingleNode("connectionStrings")

            if ($locStrings -ne $null)
            {
                $connectionStrings = $locStrings
            }
        }

        if ($connectionStrings -eq $null)
        {
            $connectionStrings = $xml.CreateElement("connectionStrings")
            $root.AppendChild($connectionStrings) | Out-Null
        }
    }

    $xpath = "add[@name='" + $name + "']"
    $add = $connectionStrings.SelectSingleNode($xpath)
    if ($add -eq $null)
    {
        Write-Output "Adding new connection string setting..."
        $add = $xml.CreateElement("add")
        $connectionStrings.AppendChild($add) | Out-Null
    }
    else
    {
        Write-Output "Updating existing connection string setting..."
    }

    $add.SetAttribute("name", $name)
    $add.SetAttribute("connectionString", $connectionString)
    $add.SetAttribute("providerName", $providerName)
    Write-Output $add | Format-List

    $xml.Save($ConfigPath)
}

Close Notepad, and then click Save to save Utility.ps1
In Windows PowerShell enter the following command to add the Utility.ps1 script as a module for the current Windows PowerShell session.
```
import-module .\Utility.ps1
```
In Windows PowerShell you use the UpdateConnectionString function to add the new connection string. You must choose the correct data source based on whether you have installed Microsoft SQL Server or SQL Server Express on the computer used for this tutorial.
- If you have only SQL Server Express installed, use the following command, which uses SQL Server Express on the local computer as the data source:
```
UpdateConnectionString "OrderService_PS" "Data Source=.\SQLEXPRESS;Initial Catalog=OrderService_PS;Integrated Security=True"
```
- If you have installed SQL Server, use the following command, which uses SQL Server as the data source:
```
UpdateConnectionString "OrderService_PS" "Data Source=localhost;Initial Catalog=OrderService_PS;Integrated Security=True"
```
Verify the new connection string by running the Internet Information Services (IIS) Manager, and then double-click the Monitoring Database Configuration applet. This should display the new connection string named OrderService_PS along with the default connection strings. The status for the new connection string should be Initialized.

The Order Service application can now be configured by AppFabric to use the OrderService_PS store for monitoring and persistence.

Configuring the Application to Use the Monitoring and Persistence Database

To configure the Order Service_PS Web site to use the new store for monitoring

In Windows PowerShell enter the following command to configure monitoring for the OrderService_PS Web site to use the new store.
```
Set-ASAppMonitoring -SiteName OrderService_PS -MonitoringLevel HealthMonitoring -ConnectionStringName OrderService_PS
```

Verify that your output from running the command looks similar to the following, which shows the monitoring settings applied to the Web site.

ConnectionStringName : OrderService_PS
ConnectionString     : Data Source=localhost;Initial Catalog=OrderService_PS;Integrated Security=True
IsEnabled            : True
MonitoringLevel      : HealthMonitoring
ProviderId           : c37234f8-4eae-41c8-9bd4-cd42706d4219
ProviderName         : System.Data.SqlClient
TrackingProfile      : HealthMonitoring Tracking Profile
SiteName             : OrderService_PS
VirtualPath          : /

To configure the OrderService_PS Web site to also use the new store for persistence

In Windows PowerShell execute the following command.

Set-ASAppSqlServicePersistence -SiteName OrderService_PS -ConnectionStringName OrderService_PS

Verify that your output from running the command looks similar to the following output, which shows the persistence settings applied to the Web site.

ConnectionString              :
ConnectionStringName          : OrderService_PS
HostLockRenewalPeriod         : 00:00:20
InstanceCompletionAction      : DeleteNothing
InstanceEncodingOption        : GZip
InstanceLockedExceptionAction : BasicRetry
AuthorizedWindowsGroup        : AS_Administrators
IsLocal                       : True
BehaviorName                  :

Enabling the net.pipe Protocol

The net.pipe protocol should be already enabled for the OrderWorkflowService Web application if you followed the step in the Lesson 3: Configuring the HRApplicationServices Application of the Tutorial Using the Windows Server AppFabric Interface. However, this section shows you how to enable the protocol with Windows PowerShell. The ApplicationServer module for Windows PowerShell does not expose a cmdlet for this operation. Instead, the operation is performed by using Appcmd.exe. For more information about Appcmd.exe see the following link: Appcmd.exe (https://go.microsoft.com/fwlink/?LinkId=169337).

To enable the net.pipe protocol for the OrderWorkflowService Web application, execute the following command in Windows PowerShell.

.$env:SystemRoot\System32\inetsrv\appcmd.exe set app "OrderService_PS/OrderWorkflowService" /enabledProtocols:"http,net.pipe"

Appcmd.exe will report the success of the operation in Windows PowerShell as follows.

APP object "OrderService_PS/OrderWorkflowService" changed

What Did I Just Do?

In this lesson you created a new monitoring and persistence store by using AppFabric cmdlets. You also created a new connection string in the Web.config file and then configured the OrderService_PS Web site to use the new store for monitoring and persistence. You can add all these commands to a Windows PowerShell script to automate application configuration.

Next Steps

In Lesson 4: Monitoring the Order Service with Windows PowerShell, you will learn how to monitor applications by using AppFabric cmdlets.