xWebAdministration

The xWebAdministration module contains the xIisModule, xWebAppPool, xWebsite, xWebApplication, xWebVirtualDirectory, and xWebConfigKeyValue DSC resources for creating and configuring various IIS artifacts.

Contributing

Please check out common DSC Resources contributing guidelines.

Resources

xIISModule

Path: The path to the module to be registered.
Name: The logical name to register the module as in IIS.
RequestPath: The allowed request paths, such as *.php
Verb: An array of allowed verbs, such as get and post.
SiteName: The name of the Site to register the module for. If empty, the resource will register the module with all of IIS.
ModuleType: The type of the module. Currently, only FastCgiModule is supported.
Ensure: Ensures that the module is Present or Absent.

xWebAppPool

Name: The desired name of the web application pool
Ensure: Should the application pool be present or absent
State: State of the application pool – started or stopped

xWebsite

Name: The desired name of the website.
PhysicalPath: The path to the files that compose the website.
State: State of the website: { Started | Stopped }
BindingInfo: Website's binding information.
ApplicationPool: The website’s application pool.
Ensure: Ensures that the website is Present or Absent.

xWebApplication

Website: Name of website with which the web application is associated.
Name: The desired name of the web application.
WebAppPool: Web application’s application pool.
PhysicalPath: The path to the files that compose the web application.
Ensure: Ensures that the web application is Present or Absent.

xWebVirtualDirectory

Website: Name of website with which virtual directory is associated
WebApplication: Web application name for the virtual directory
PhysicalPath: The path to the files that compose the virtual directory
Name: The name of the virtual directory
Ensure: Ensures if the virtual directory is Present or Absent.
State: State of the application pool: { Started | Stopped }

xWebConfigKeyValue

WebsitePath: Path to website location (IIS or WebAdministration format).
ConfigSection: Section to update (only AppSettings supported as of now).
KeyValuePair: Key value pair for AppSettings (ItemCollection format).

Versions

Unreleased

Fixed issue in xWebApplication where Set-TargetResource created a folder instead of an applicaition
- Added Tests to xWebApplication which will allow more changes if desired.
Fixed binding compare issue in xWebsite which was causing bindings to be changed every DSC check.
Modified README.MD to clean up Code Formatting
Modified all unit/integration tests to utilize template system.
xWebAppPool is now has feature parity to cWebAppPool - should now support most changes.
Added Unit tests to IISFeatureDelegation, general script clean up
Refactored xIisHandle to load script variables once, added unit tests.

1.8.0.0

Modified xWebsite to allow Server Name Indication when specifiying SSL certificates.
Change Test Get-Website to match other function
Removed xDscResourceDesigner tests
Suppress extra verbose messages when -verbose is specified to Start-DscConfiguration
Moved tests into child folders Unit and Integration
Added PSDesiredStateConfiguration to Import-DscResource statement
Fixed issue where Set-TargetResource was being run unexpectedly
Added Tests to MSFT_xWebVirtualDirectory
xWebsite tests updates
xWebVirtualDirectory tests updates

1.7.0.0

Added following resources:
- xIisHandler
- xIisFeatureDelegation
- xIisMimeTypeMapping
- xWebAppPoolDefaults
- xWebSiteDefaults
Modified xWebsite schema to make PhysicalPath required

1.6.0.0

Fixed bug in xWebsite resource regarding incorrect name of personal certificate store.

1.5.0.0

xWebsite:
- Fix issue with Get-Website when there are multiple sites.
- Fix issue when trying to add a new website when no websites currently exist.
- Fix typos.

1.4.0.0

Changed Key property in MSFT_xWebConfigKeyValue to be a Key, instead of Required. This allows multiple keys to be configured within the same web.config file.

1.3.2.4

Fixed the confusion with mismatched versions and xWebDeploy resources
Removed BakeryWebsite.zip for legal reasons. Please read Examples\README.md for the workaround.

1.3.2.3

Fixed variable name typo in MSFT_xIisModule.
Added OutputType attribute to Test-TargetResource and Get-TargetResource in MSFT_xWebSite.

1.3.2.2

Documentation only change. Module manifest metadata changed to improve PowerShell Gallery experience.

1.3.2.1

Documentation-only change, added metadata to module manifest

1.3.2

Added xIisModule

1.2

Added the xWebAppPool, xWebApplication, xWebVirtualDirectory, and xWebConfigKeyValue.

1.1.0.0

Added support for HTTPS protocol
Updated binding information to include Certificate information for HTTPS
Removed protocol property. Protocol is included in binding information
Bug fixes

1.0.0.0

Initial release with the following resources
- xWebsite

Examples

Registering PHP

When configuring an IIS Application that uses PHP, you first need to register the PHP CGI module with IIS. The following xPhp configuration downloads and installs the prerequisites for PHP, downloads PHP, registers the PHP CGI module with IIS and sets the system environment variable that PHP needs to run.

Note: This example is intended to be used as a composite resource, so it does not use Configuration Data. Please see the Composite Configuration Blog on how to use this configuration in another configuration.

# Composite configuration to install the IIS pre-requisites for PHP
Configuration IisPreReqs_php
{
    param
    (
        [Parameter(Mandatory = $true)]
        [Validateset("Present","Absent")]
        [String]
        $Ensure
    )
    foreach ($Feature in @("Web-Server","Web-Mgmt-Tools","web-Default-Doc", `
            "Web-Dir-Browsing","Web-Http-Errors","Web-Static-Content",`
            "Web-Http-Logging","web-Stat-Compression","web-Filtering",`
            "web-CGI","web-ISAPI-Ext","web-ISAPI-Filter"))
    {
        WindowsFeature "$Feature$Number"
        {
            Ensure = $Ensure
            Name = $Feature
        }
    }
}

# Composite configuration to install PHP on IIS
configuration xPhp
{
    param
    (
        [Parameter(Mandatory = $true)]
        [switch] $installMySqlExt,
        [Parameter(Mandatory = $true)]
        [string] $PackageFolder,
        [Parameter(Mandatory = $true)]
        [string] $DownloadUri,
        [Parameter(Mandatory = $true)]
        [string] $Vc2012RedistDownloadUri,
        [Parameter(Mandatory = $true)]
        [String] $DestinationPath,
        [Parameter(Mandatory = $true)]
        [string] $ConfigurationPath
    )
        # Make sure the IIS Prerequisites for PHP are present
        IisPreReqs_php Iis
        {
            Ensure = "Present"
            # Removed because this dependency does not work in
            # Windows Server 2012 R2 and below
            # This should work in WMF v5 and above
            # DependsOn = "[File]PackagesFolder"
        }

        # Download and install Visual C Redist2012 from chocolatey.org
        Package vcRedist
        {
            Path = $Vc2012RedistDownloadUri
            ProductId = "{CF2BEA3C-26EA-32F8-AA9B-331F7E34BA97}"
            Name = "Microsoft Visual C++ 2012 x64 Minimum Runtime - 11.0.61030"
            Arguments = "/install /passive /norestart"
        }

        $phpZip = Join-Path $PackageFolder "php.zip"

        # Make sure the PHP archine is in the package folder
        xRemoteFile phpArchive
        {
            uri = $DownloadURI
            DestinationPath = $phpZip
        }

        # Make sure the content of the PHP archine are in the PHP path
        Archive php
        {
            Path = $phpZip
            Destination  = $DestinationPath
        }

        if ($installMySqlExt )
        {
            # Make sure the MySql extention for PHP is in the main PHP path
            File phpMySqlExt
            {
                SourcePath = "$($DestinationPath)\ext\php_mysql.dll"
                DestinationPath = "$($DestinationPath)\php_mysql.dll"
                Ensure = "Present"
                DependsOn = @("[Archive]PHP")
                MatchSource = $true
            }
        }

        # Make sure the php.ini is in the Php folder
        File PhpIni
        {
            SourcePath = $ConfigurationPath
            DestinationPath = "$($DestinationPath)\php.ini"
            DependsOn = @("[Archive]PHP")
            MatchSource = $true
        }

        # Make sure the php cgi module is registered with IIS
		xIisModule phpHandler
		{
			Name = "phpFastCgi"
			Path = "$($DestinationPath)\php-cgi.exe"
			RequestPath = "*.php"
			Verb = "*"
			Ensure = "Present"
			DependsOn = @("[Package]vcRedist","[File]PhpIni")
			# Removed because this dependency does not work in
			# Windows Server 2012 R2 and below
			# This should work in WMF v5 and above
			# "[IisPreReqs_php]Iis"
		}

        # Make sure the php binary folder is in the path
        Environment PathPhp
        {
            Name = "Path"
            Value = ";$($DestinationPath)"
            Ensure = "Present"
            Path = $true
            DependsOn = "[Archive]PHP"
        }
}

xPhp -PackageFolder "C:\packages" `
    -DownloadUri  -DownloadUri "http://windows.php.net/downloads/releases/php-5.5.13-Win32-VC11-x64.zip" `
    -Vc2012RedistDownloadUri "http://download.microsoft.com/download/1/6/B/16B06F60-3B20-4FF2-B699-5E9B7962F9AE/VSU_4/vcredist_x64.exe" `
    -DestinationPath "C:\php" `
    -ConfigurationPath "C:\MyPhp.ini" `
    -installMySqlExt $false

Stopping the default website

When configuring a new IIS server, several references recommend removing or stopping the default website for security purposes. This example sets up your IIS web server by installing IIS Windows Feature. After that, it will stop the default website by setting State = Stopped.

Configuration Sample_xWebsite_StopDefault
{
    param
    (
        # Target nodes to apply the configuration
        [string[]]$NodeName = 'localhost'
    )
    # Import the module that defines custom resources
    Import-DscResource -Module xWebAdministration
    Node $NodeName
    {
        # Install the IIS role
        WindowsFeature IIS
        {
            Ensure          = "Present"
            Name            = "Web-Server"
        }
        # Stop the default website
        xWebsite DefaultSite
        {
            Ensure          = "Present"
            Name            = "Default Web Site"
            State           = "Stopped"
            PhysicalPath    = "C:\inetpub\wwwroot"
            DependsOn       = "[WindowsFeature]IIS"
        }
    }
}

Create a new website

While setting up IIS and stopping the default website is interesting, it isn’t quite useful yet. After all, people typically use IIS to set up websites of their own with custom protocol and bindings. Fortunately, using DSC, adding another website is as simple as using the File and xWebsite resources to copy the website content and configure the website.

Configuration Sample_xWebsite_NewWebsite
{
    param
    (
        # Target nodes to apply the configuration
        [string[]]$NodeName = 'localhost',
        # Name of the website to create
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String]$WebSiteName,
        # Source Path for Website content
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String]$SourcePath,
        # Destination path for Website content
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [String]$DestinationPath
    )

    # Import the module that defines custom resources
    Import-DscResource -Module xWebAdministration
    Node $NodeName
    {
        # Install the IIS role
        WindowsFeature IIS
        {
            Ensure          = "Present"
            Name            = "Web-Server"
        }

        # Install the ASP .NET 4.5 role
        WindowsFeature AspNet45
        {
            Ensure          = "Present"
            Name            = "Web-Asp-Net45"
        }

        # Stop the default website
        xWebsite DefaultSite
        {
            Ensure          = "Present"
            Name            = "Default Web Site"
            State           = "Stopped"
            PhysicalPath    = "C:\inetpub\wwwroot"
            DependsOn       = "[WindowsFeature]IIS"
        }

        # Copy the website content
        File WebContent
        {
            Ensure          = "Present"
            SourcePath      = $SourcePath
            DestinationPath = $DestinationPath
            Recurse         = $true
            Type            = "Directory"
            DependsOn       = "[WindowsFeature]AspNet45"
        }

        # Create the new Website with HTTPS
        xWebsite NewWebsite
        {
            Ensure          = "Present"
            Name            = $WebSiteName
            State           = "Started"
            PhysicalPath    = $DestinationPath
            BindingInfo     = @(
                MSFT_xWebBindingInformation
                {
                    Protocol              = "HTTPS"
                    Port                  = 8443
                    CertificateThumbprint = "71AD93562316F21F74606F1096B85D66289ED60F"
                    CertificateStoreName  = "WebHosting"
                },
                MSFT_xWebBindingInformation
                {
                    Protocol              = "HTTPS"
                    Port                  = 8444
                    CertificateThumbprint = "DEDDD963B28095837F558FE14DA1FDEFB7FA9DA7"
                    CertificateStoreName  = "MY"
                }
            )
            DependsOn       = "[File]WebContent"
        }
    }
}

Creating the default website using configuration data

In this example, we’ve moved the parameters used to generate the website into a configuration data file. All of the variant portions of the configuration are stored in a separate file. This can be a powerful tool when using DSC to configure a project that will be deployed to multiple environments. For example, users managing larger environments may want to test their configuration on a small number of machines before deploying it across many more machines in their production environment.

Configuration files are made with this in mind. This is an example configuration data file (saved as a .psd1).

Configuration Sample_xWebsite_FromConfigurationData
{
    # Import the module that defines custom resources
    Import-DscResource -Module xWebAdministration

    # Dynamically find the applicable nodes from configuration data
    Node $AllNodes.where{$_.Role -eq "Web"}.NodeName
    {
        # Install the IIS role
        WindowsFeature IIS
        {
            Ensure          = "Present"
            Name            = "Web-Server"
        }

        # Install the ASP .NET 4.5 role
        WindowsFeature AspNet45
        {
            Ensure          = "Present"
            Name            = "Web-Asp-Net45"
        }

        # Stop an existing website (set up in Sample_xWebsite_Default)
        xWebsite DefaultSite
        {
            Ensure          = "Present"
            Name            = "Default Web Site"
            State           = "Stopped"
            PhysicalPath    = $Node.DefaultWebSitePath
            DependsOn       = "[WindowsFeature]IIS"
        }

        # Copy the website content
        File WebContent
        {
            Ensure          = "Present"
            SourcePath      = $Node.SourcePath
            DestinationPath = $Node.DestinationPath
            Recurse         = $true
            Type            = "Directory"
            DependsOn       = "[WindowsFeature]AspNet45"
        }

        # Create a new website
        xWebsite BakeryWebSite
        {
            Ensure          = "Present"
            Name            = $Node.WebsiteName
            State           = "Started"
            PhysicalPath    = $Node.DestinationPath
            DependsOn       = "[File]WebContent"
        }
    }
}

# Content of configuration data file (e.g. ConfigurationData.psd1) could be:
# Hashtable to define the environmental data
@{
    # Node specific data
    AllNodes = @(
       # All the WebServer has following identical information
       @{
            NodeName           = "*"
            WebsiteName        = "FourthCoffee"
            SourcePath         = "C:\BakeryWebsite\"
            DestinationPath    = "C:\inetpub\FourthCoffee"
            DefaultWebSitePath = "C:\inetpub\wwwroot"
       },
       @{
            NodeName           = "WebServer1.fourthcoffee.com"
            Role               = "Web"
        },
       @{
            NodeName           = "WebServer2.fourthcoffee.com"
            Role               = "Web"
        }
    );
}
# Pass the configuration data to configuration as follows:
Sample_xWebsite_FromConfigurationData -ConfigurationData ConfigurationData.psd1

All resources (end-to-end scenario)

# End to end sample for xWebAdministration

configuration Sample_EndToEndxWebAdministration
{

    Node $AllNodes.NodeName
    {
        # Create a Web Application Pool
        xWebAppPool NewWebAppPool
        {
            Name   = $Node.WebAppPoolName
            Ensure = "Present"
            State  = "Started"
        }

        #Create a New Website with Port
        xWebSite NewWebSite
        {
            Name   = $Node.WebSiteName
            Ensure = "Present"
            BindingInfo = MSFT_xWebBindingInformation
            {
                Port = $Node.Port
            }

            PhysicalPath = $Node.PhysicalPathWebSite
            State = "Started"
            DependsOn = @("[xWebAppPool]NewWebAppPool")
        }

        #Create a new Web Application
        xWebApplication NewWebApplication
        {
            Name = $Node.WebApplicationName
            Website = $Node.WebSiteName
            WebAppPool =  $Node.WebAppPoolName
            PhysicalPath = $Node.PhysicalPathWebApplication
            Ensure = "Present"
            DependsOn = @("[xWebSite]NewWebSite")
        }

        #Create a new virtual Directory
        xWebVirtualDirectory NewVirtualDir
        {
            Name = $Node.WebVirtualDirectoryName
            Website = $Node.WebSiteName
            WebApplication =  $Node.WebApplicationName
            PhysicalPath = $Node.PhysicalPathVirtualDir
            Ensure = "Present"
            DependsOn = @("[xWebApplication]NewWebApplication")
        }

        File CreateWebConfig
        {
             DestinationPath = $Node.PhysicalPathWebSite + "\web.config"
             Contents = "&amp;amp;amp;amp;lt;?xml version=`"1.0`" encoding=`"UTF-8`"?&amp;amp;amp;amp;gt;
                            &amp;amp;amp;amp;lt;configuration&amp;amp;amp;amp;gt;
                            &amp;amp;amp;amp;lt;/configuration&amp;amp;amp;amp;gt;"
                    Ensure = "Present"
             DependsOn = @("[xWebVirtualDirectory]NewVirtualDir")
        }

        xWebConfigKeyValue ModifyWebConfig
        {
            Ensure = "Present"
            ConfigSection = "AppSettings"
            KeyValuePair = @{key="key1";value="value1"}
            IsAttribute = $false
            WebsitePath = "IIS:\sites\" + $Node.WebsiteName
            DependsOn = @("[File]CreateWebConfig")
        }
    }
}

#You can place the below in another file to create multiple websites using the same configuration block.
$Config = @{
    AllNodes = @(
        @{
            NodeName = "localhost";
            WebAppPoolName = "TestAppPool";
            WebSiteName = "TestWebSite";
            PhysicalPathWebSite = "C:\web\webSite";
            WebApplicationName = "TestWebApplication";
            PhysicalPathWebApplication = "C:\web\webApplication";
            WebVirtualDirectoryName = "TestVirtualDir";
            PhysicalPathVirtualDir = "C:\web\virtualDir";
            Port = 100
        }
    )
}

Sample_EndToEndxWebAdministration -ConfigurationData $config
Start-DscConfiguration ./Sample_EndToEndxWebAdministration -wait -Verbose

Name		Name	Last commit message	Last commit date
Latest commit History 225 Commits
DSCResources		DSCResources
Examples		Examples
Tests		Tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
appveyor.yml		appveyor.yml
xWebAdministration.psd1		xWebAdministration.psd1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

xWebAdministration

Contributing

Resources

xIISModule

xWebAppPool

xWebsite

xWebApplication

xWebVirtualDirectory

xWebConfigKeyValue

Versions

Unreleased

1.8.0.0

1.7.0.0

1.6.0.0

1.5.0.0

1.4.0.0

1.3.2.4

1.3.2.3

1.3.2.2

1.3.2.1

1.3.2

1.2

1.1.0.0

1.0.0.0

Examples

Registering PHP

Stopping the default website

Create a new website

Creating the default website using configuration data

All resources (end-to-end scenario)

About

Releases

Packages

Languages

License

jianyunt/xWebAdministration

Folders and files

Latest commit

History

Repository files navigation

xWebAdministration

Contributing

Resources

xIISModule

xWebAppPool

xWebsite

xWebApplication

xWebVirtualDirectory

xWebConfigKeyValue

Versions

Unreleased

1.8.0.0

1.7.0.0

1.6.0.0

1.5.0.0

1.4.0.0

1.3.2.4

1.3.2.3

1.3.2.2

1.3.2.1

1.3.2

1.2

1.1.0.0

1.0.0.0

Examples

Registering PHP

Stopping the default website

Create a new website

Creating the default website using configuration data

All resources (end-to-end scenario)

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages