diff --git a/README.md b/README.md index 8086d4b8e..f98a826c5 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,10 @@ Currently, only FastCgiModule is supported. ## Versions +### 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 diff --git a/TechNetDocumentation_xWebAdministration.html b/TechNetDocumentation_xWebAdministration.html deleted file mode 100644 index ee92a46ea..000000000 --- a/TechNetDocumentation_xWebAdministration.html +++ /dev/null @@ -1,1430 +0,0 @@ - -
-
-

- - - Introduction -
- -

-
-

- - The xWebAdministration module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module contains - the xIISModule, xWebAppPool, xWebsite, - xWebApplication, xWebVirtualDirectory & xWebConfigKeyValue resources. These DSC resources allow creation and configuration of various IIS artifacts. - -

-

- - All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service. The "x" in xWebAdministration stands for experimental, which - means that these resources will be fix forward and monitored by the module owner(s). - -

-

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

-

- - If you would like to modify xWebAdministration module, feel free. When modifying, please update the module name, resource friendly name, and MOF class name (instructions below). As specified in the license, - you may copy or modify this resource as long as they are used on the Windows Platform. - -

-

- - For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the - PowerShell Blog (this is a good starting point). There - are also great community resources, such as - PowerShell.org - , or PowerShell Magazine. For more information on the DSC Resource Kit, check out - this blog post. - -

-
-

- Installation - -
- -

-
-

- To install xWebAdministration module: -

- -

To confirm installation:

- -

- Requirements -

-

- - This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). It also requires IIS features. To easily use PowerShell 4.0 on older operating systems, - - install WMF 4.0 - - .  Please read the installation instructions that are present on both the download page - and the release notes for WMF 4.0. - -

-

- Description -

-

- - The xWebAdministration module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module contains - the xIISModule, xWebAppPool, xWebsite, - xWebApplication, xWebVirtualDirectory & xWebConfigKeyValue resources. These DSC resources allow creation and configuration of various IIS artifacts. - -   -

-

Details

-

- xIISModule resource has following properties: -

- -

- xWebAppPool resource has following properties: -

- -

- xWebsite resource has following properties: -

- -

- xWebApplication resource has following properties: -

- -

- xWebVirtualDirectory resource has following properties: -

- -

- xWebConfigKeyValue resource has following properties: -

- -

Renaming Requirements

-

When making changes to these resources, we suggest the following practice:

-
    -
  1. -

    - - Update the following names by replacing MSFT with your company/community name and replacing the - “x” with "c" (short for "Community") or another prefix of your choice: - -

    -
      -
    • - - Module name (ex: xWebAdministration becomes - cWebAdministration) - -
      • -
    • - - Resource folder (ex: MSFT_xWebsite becomes - Contoso_cWebsite) - -
      • -
    • - - Resource Name (ex: MSFT_xWebsite becomes - Contoso_cWebsite) - -
      • -
    • - - Resource Friendly Name (ex: xWebsite becomes - cWebsite) - -
      • -
    • - - MOF class name (ex: MSFT_xWebsite becomes - Contoso_cWebsite) - -
      • -
    • - - Filename for the <resource>.schema.mof (ex: MSFT_Website.schema.mof becomes - Contoso_cWebsite.schema.mof) - -
      • -
    -
    2. -
  2. -

    - Update module and metadata information in the module manifest -

    -
    3. -
  3. -

    - Update any configuration that use these resources -

    -
    4. -
-

- - - - We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "MSFT_WebAdministration" or "WebAdministration").  - If the next version of Windows Server ships with a "WebAdministration" resource, we don't want to break any configurations that use any community modifications.  Please keep a prefix such as "c" on all community modifications. - - - -

-

- Example: 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 sample 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 in configuration in another configuration. -

-
-
-
PowerShell
-
- Edit| - Remove -
- - -
-
# 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  
-
-
-
-
-
 
-

 

-

- Example: 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 webserver by installing IIS Windows Feature. Following that, it will - stop the default website by setting “State = Stopped ”. - -

-
-
-
PowerShell
-
- Edit| - Remove -
- - -
-
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" 
-        } 
-    } 
-}
-
-
-
-
-

- Example: Create a new website -

-
-

- - While setting up IIS and stopping the default website is interesting, it isn’t quite useful yet. After all, typically people 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. - -

-
-
-
-
PowerShell
-
- Edit| - Remove -
- - -
-
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" 
-                             } 
-            DependsOn       = "[File]WebContent" 
-        } 
-    } 
-} 
-
-
-
-
-
 
-

Example: 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).   - -

-
-
-
-
PowerShell
-
- Edit| - Remove -
- - -
-
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
-
-
-
-
-

- - Example: All Resources (end to end scenario)
- -

-

-
-
-
PowerShell
-
- Edit| - Remove -
- - -
-
# 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 = "<?xml version=`"1.0`" encoding=`"UTF-8`"?> 
-                        <configuration> 
-                        </configuration>" 
-                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 
-
-
-
-
-
 
-

-

Versions

-
-

1.0.0.0

-
-
-
    -
  • -

    - Initial release with the following resources -

    -
      -
    • -

      - xWebsite -

      -
      • -
    -
    • -
-
-
-

- 1.1.0.0 -

-
    -
  • -

    - Added support for HTTPS protocol -

    -
    • -
-
    -
  • -

    - Updated binding information to include Certificate inforation for HTTPS -

    -
    • -
  • -

    - Removed protocol property. Protocol is included in binding information -

    -
    • -
-
    -
  • -

    Bug fixes

    -
    • -
- -

1.2

- -
    -
  • - Added the - - xWebAppPool, -   - xWebApplication, xWebVirtualDirectory & xWebConfigKeyValue - -
    • -
-

1.3.2

-
    -
  • Added xIisModule
    • -
-

1.3.2.1

-
    -
  • Documentation-only change, added metadata to module manifest
    • -
-

1.3.2.2

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

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.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.5

-
    -
  • 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.
    • -
- -   - -
-
-
-
- -
- - \ No newline at end of file diff --git a/xWebAdministration.psd1 b/xWebAdministration.psd1 index 1d5939b67..7656aeec1 100644 --- a/xWebAdministration.psd1 +++ b/xWebAdministration.psd1 @@ -1,6 +1,6 @@ @{ # Version number of this module. -ModuleVersion = '1.3.2.4' +ModuleVersion = '1.4.0.0' # ID used to uniquely identify this module GUID = 'b3239f27-d7d3-4ae6-a5d2-d9a1c97d6ae4'