DSCResources/DSC_WebSite/en-US/about_WebSite.help.txt

.NAME
    WebSite
 
.DESCRIPTION
    The WebSite DSC resource is used to...
 
    ## Requirements
 
    * Target machine must be running Windows Server 2012 R2 or later.
 
    ## Known issues
 
    All issues are not listed here, see https://github.com/dsccommunity/WebAdministration/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+WebSite.
 
.PARAMETER Ensure
    Write - String
    Allowed values: Present, Absent
    Ensures that the website is Present or Absent. Defaults to Present.
 
.PARAMETER Name
    Key - String
    The desired name of the website.
 
.PARAMETER SiteId
    Write - UInt32
    Optional. The desired IIS site Id for the website.
 
.PARAMETER PhysicalPath
    Write - String
    The path to the files that compose the website.
 
.PARAMETER State
    Write - String
    Allowed values: Started, Stopped
    The state of the website.
 
.PARAMETER ApplicationPool
    Write - String
    The name of the website?s application pool.
 
.PARAMETER BindingInfo
    Write - InstanceArray
    Website's binding information in the form of an array of embedded instances of the DSC_WebBindingInformation CIM class.
 
.PARAMETER DefaultPage
    Write - StringArray
    One or more names of files that will be set as Default Documents for this website.
 
.PARAMETER EnabledProtocols
    Write - String
    The protocols that are enabled for the website.
 
.PARAMETER ServerAutoStart
    Write - Boolean
    When set to $true this will enable Autostart on a Website
 
.PARAMETER AuthenticationInfo
    Write - Instance
    Hashtable containing authentication information (Anonymous, Basic, Digest, Windows)
 
.PARAMETER PreloadEnabled
    Write - Boolean
    When set to $true this will allow WebSite to automatically start without a request
 
.PARAMETER ServiceAutoStartEnabled
    Write - Boolean
    When set to $true this will enable application Autostart (application initalization without an initial request) on a Website
 
.PARAMETER ServiceAutoStartProvider
    Write - String
    Adds a AutostartProvider
 
.PARAMETER ApplicationType
    Write - String
    Adds a AutostartProvider ApplicationType
 
.PARAMETER LogPath
    Write - String
    The directory to be used for logfiles
 
.PARAMETER LogFlags
    Write - StringArray
    Allowed values: Date, Time, ClientIP, UserName, SiteName, ComputerName, ServerIP, Method, UriStem, UriQuery, HttpStatus, Win32Status, BytesSent, BytesRecv, TimeTaken, ServerPort, UserAgent, Cookie, Referer, ProtocolVersion, Host, HttpSubStatus
    The W3C logging fields
 
.PARAMETER LogPeriod
    Write - String
    Allowed values: Hourly, Daily, Weekly, Monthly, MaxSize
    How often the log file should rollover
 
.PARAMETER LogTruncateSize
    Write - String
    How large the file should be before it is truncated
 
.PARAMETER LoglocalTimeRollover
    Write - Boolean
    Use the localtime for file naming and rollover
 
.PARAMETER LogFormat
    Write - String
    Allowed values: IIS, W3C, NCSA
    Format of the Logfiles. Only W3C supports LogFlags
 
.PARAMETER LogTargetW3C
    Write - String
    Allowed values: File, ETW, File,ETW
    Specifies whether IIS will use Event Tracing or file logging
 
.PARAMETER LogCustomFields
    Write - InstanceArray
    Custom logging field information in the form of an array of embedded instances of DSC_LogCustomFieldInformation CIM class
 
.EXAMPLE 1
 
When specifying a HTTPS web binding you can also specify a certifcate subject, for cases where the certificate
is being generated by the same configuration using something like xCertReq.
 
Configuration Sample_WebSite_NewWebsite_UsingCertificateSubject
{
    param
    (
        # Target nodes to apply the configuration
        [string[]]
        $NodeName = 'localhost',
        # Name of the website to create
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $WebSiteName,
        # Source Path for Website content
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $SourcePath,
        # Destination path for Website content
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $DestinationPath
    )
 
    # Import the module that defines custom resources
    Import-DscResource -Module WebAdministrationDsc
    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
        WebSite 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
        WebSite NewWebsite
        {
            Ensure = 'Present'
            Name = $WebSiteName
            State = 'Started'
            PhysicalPath = $DestinationPath
            BindingInfo = @(
                DSC_WebBindingInformation
                {
                    Protocol = 'HTTPS'
                    Port = 8444
                    CertificateSubject = 'CN=CertificateSubject'
                    CertificateStoreName = 'MY'
                }
            )
            DependsOn = '[File]WebContent'
        }
    }
}
 
.EXAMPLE 2
 
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 WebSite resources to
copy the website content and configure the website.
 
Configuration Sample_WebSite_NewWebsite_UsingCertificateThumbprint
{
    param
    (
        # Target nodes to apply the configuration
        [string[]]
        $NodeName = 'localhost',
        # Name of the website to create
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $WebSiteName,
        # Source Path for Website content
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $SourcePath,
        # Destination path for Website content
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $DestinationPath
    )
 
    # Import the module that defines custom resources
    Import-DscResource -Module WebAdministrationDsc
    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
        WebSite 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
        WebSite NewWebsite
        {
            Ensure = 'Present'
            Name = $WebSiteName
            State = 'Started'
            PhysicalPath = $DestinationPath
            BindingInfo = @(
                DSC_WebBindingInformation
                {
                    Protocol = 'HTTPS'
                    Port = 8443
                    CertificateThumbprint = '71AD93562316F21F74606F1096B85D66289ED60F'
                    CertificateStoreName = 'WebHosting'
                }
                DSC_WebBindingInformation
                {
                    Protocol = 'HTTPS'
                    Port = 8444
                    CertificateThumbprint = 'DEDDD963B28095837F558FE14DA1FDEFB7FA9DA7'
                    CertificateStoreName = 'MY'
                }
            )
            DependsOn = '[File]WebContent'
        }
    }
}
 
.EXAMPLE 3
 
 
configuration Sample_WebSite_NewWebsite
{
    param
    (
        # Target nodes to apply the configuration
        [String[]]
        $NodeName = 'localhost',
 
        # Name of the website to create
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $WebSiteName,
 
        # Optional Site Id for the website
        [Parameter()]
        [UInt32]
        $SiteId,
 
        # Source Path for Website content
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $SourcePath,
 
        # Destination path for Website content
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $DestinationPath
    )
 
    # Import the module that defines custom resources
    Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration
 
    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
        WebSite DefaultSite
        {
            Ensure = 'Present'
            Name = 'Default Web Site'
            State = 'Stopped'
            ServerAutoStart = $false
            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
        WebSite NewWebsite
        {
            Ensure = 'Present'
            Name = $WebSiteName
            SiteId = $SiteId
            State = 'Started'
            ServerAutoStart = $true
            PhysicalPath = $DestinationPath
            DependsOn = '[File]WebContent'
        }
    }
}
 
.EXAMPLE 4
 
 
Configuration Sample_WebSite_NewWebsiteFromConfigurationData
{
    # Import the module that defines custom resources
    Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration
 
    # 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_WebSite_Default)
        WebSite DefaultSite
        {
            Ensure = 'Present'
            Name = 'Default Web Site'
            State = 'Stopped'
            ServerAutoStart = $false
            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
        WebSite BakeryWebSite
        {
            Ensure = 'Present'
            Name = $Node.WebsiteName
            State = 'Started'
            ServerAutoStart = $true
            PhysicalPath = $Node.DestinationPath
            DependsOn = '[File]WebContent'
        }
    }
}
 
# Hashtable to define the environmental data
$ConfigurationData = @{
    # Node specific data
    AllNodes = @(
 
        # All the WebServers have the 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'
        }
    );
}
 
.EXAMPLE 5
 
 
configuration Sample_WebSite_RemoveDefault
{
    param
    (
        # Target nodes to apply the configuration
        [String[]] $NodeName = 'localhost'
    )
 
    # Import the module that defines custom resources
    Import-DscResource -Module WebAdministrationDsc, PSDesiredStateConfiguration
 
    Node $NodeName
    {
        # Install the IIS role
        WindowsFeature IIS
        {
            Ensure = 'Present'
            Name = 'Web-Server'
        }
 
        # Stop the default website
        WebSite DefaultSite
        {
            Ensure = 'Present'
            Name = 'Default Web Site'
            State = 'Stopped'
            ServerAutoStart = $false
            PhysicalPath = 'C:\inetpub\wwwroot'
            DependsOn = '[WindowsFeature]IIS'
        }
    }
}
 
.EXAMPLE 6
 
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_WebSite_StopDefault
{
    param
    (
        # Target nodes to apply the configuration
        [string[]]$NodeName = 'localhost'
    )
    # Import the module that defines custom resources
    Import-DscResource -Module WebAdministrationDsc
    Node $NodeName
    {
        # Install the IIS role
        WindowsFeature IIS
        {
            Ensure = "Present"
            Name = "Web-Server"
        }
        # Stop the default website
        WebSite DefaultSite
        {
            Ensure = "Present"
            Name = "Default Web Site"
            State = "Stopped"
            PhysicalPath = "C:\inetpub\wwwroot"
            DependsOn = "[WindowsFeature]IIS"
        }
    }
}
 
.EXAMPLE 7
 
 
configuration Sample_WebSite_WithSSLFlags
{
    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 WebAdministrationDsc, PSDesiredStateConfiguration
 
    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
        WebSite DefaultSite
        {
            Ensure = "Present"
            Name = "Default Web Site"
            State = "Stopped"
            ServerAutoStart = $false
            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
        # Have it set to the CertificateThumbprint
        # and set that the Server Name Indication is required
        WebSite NewWebsite
        {
            Ensure = "Present"
            Name = $WebSiteName
            State = "Started"
            PhysicalPath = $DestinationPath
            DependsOn = "[File]WebContent"
            BindingInfo = DSC_WebBindingInformation
            {
                Protocol = 'https'
                Port = '443'
                CertificateStoreName = 'MY'
                CertificateThumbprint = 'BB84DE3EC423DDDE90C08AB3C5A828692089493C'
                HostName = $WebSiteName
                IPAddress = '*'
                SSLFlags = '1'
            }
        }
    }
}