Skip to content

xWebSite

Jump to bottom
Johan Ljunggren edited this page Dec 6, 2023 · 4 revisions

xWebSite

Important

This resource has been renamed in the latest release, see WebSite. Bug fixes and new functionality will only be added to the renamed resource.

Parameters

Parameter Attribute DataType Description Allowed Values
Ensure Write String Ensures that the website is Present or Absent. Defaults to Present. Present, Absent
Name Key String The desired name of the website.
SiteId Write UInt32 Optional. The desired IIS site Id for the website.
PhysicalPath Write String The path to the files that compose the website.
State Write String The state of the website. Started, Stopped
ApplicationPool Write String The name of the website’s application pool.
BindingInfo Write MSFT_xWebBindingInformation[] Website's binding information in the form of an array of embedded instances of the MSFT_xWebBindingInformation CIM class.
DefaultPage Write StringArray[] One or more names of files that will be set as Default Documents for this website.
EnabledProtocols Write String The protocols that are enabled for the website.
ServerAutoStart Write Boolean When set to $true this will enable Autostart on a Website
AuthenticationInfo Write MSFT_xWebAuthenticationInformation Hashtable containing authentication information (Anonymous, Basic, Digest, Windows)
PreloadEnabled Write Boolean When set to $true this will allow WebSite to automatically start without a request
ServiceAutoStartEnabled Write Boolean When set to $true this will enable application Autostart (application initalization without an initial request) on a Website
ServiceAutoStartProvider Write String Adds a AutostartProvider
ApplicationType Write String Adds a AutostartProvider ApplicationType
LogPath Write String The directory to be used for logfiles
LogFlags Write StringArray[] The W3C logging fields Date, Time, ClientIP, UserName, SiteName, ComputerName, ServerIP, Method, UriStem, UriQuery, HttpStatus, Win32Status, BytesSent, BytesRecv, TimeTaken, ServerPort, UserAgent, Cookie, Referer, ProtocolVersion, Host, HttpSubStatus
LogPeriod Write String How often the log file should rollover Hourly, Daily, Weekly, Monthly, MaxSize
LogTruncateSize Write String How large the file should be before it is truncated
LoglocalTimeRollover Write Boolean Use the localtime for file naming and rollover
LogFormat Write String Format of the Logfiles. Only W3C supports LogFlags IIS, W3C, NCSA
LogTargetW3C Write String Specifies whether IIS will use Event Tracing or file logging File, ETW, File,ETW
LogCustomFields Write MSFT_xLogCustomFieldInformation[] Custom logging field information in the form of an array of embedded instances of MSFT_xLogCustomFieldInformation CIM class

MSFT_xWebBindingInformation

Parameters

Parameter Attribute DataType Description Allowed Values
Protocol Required String The protocol of the binding. This property is required. The acceptable values for this property are: http, https, msmq.formatname, net.msmq, net.pipe, net.tcp. http, https, msmq.formatname, net.msmq, net.pipe, net.tcp
BindingInformation Write String The binding information in the form a colon-delimited string that includes the IP address, port, and host name of the binding. This property is ignored for http and https bindings if at least one of the following properties is specified: IPAddress, Port, HostName.
IPAddress Write String The IP address of the binding. This property is only applicable for http and https bindings. The default value is *.
Port Write UInt16 The port of the binding. The value must be a positive integer between 1 and 65535. This property is only applicable for http (the default value is 80) and https (the default value is 443) bindings.
HostName Write String The host name of the binding. This property is only applicable for http and https bindings.
CertificateThumbprint Write String The thumbprint of the certificate. This property is only applicable for https bindings.
CertificateSubject Write String The subject of the certificate if the thumbprint isn't known. This property is only applicable for https bindings.
CertificateStoreName Write String The name of the certificate store where the certificate is located. This property is only applicable for https bindings. The acceptable values for this property are: My, WebHosting. The default value is My. My, WebHosting
SslFlags Write String The type of binding used for Secure Sockets Layer (SSL) certificates. This property is supported in IIS 8.0 or later, and is only applicable for https bindings. 0, 1, 2, 3

MSFT_xWebAuthenticationInformation

Parameters

Parameter Attribute DataType Description Allowed Values
Anonymous Write Boolean The acceptable values for this property are: $true, $false
Basic Write Boolean The acceptable values for this property are: $true, $false
Digest Write Boolean The acceptable values for this property are: $true, $false
Windows Write Boolean The acceptable values for this property are: $true, $false

MSFT_xLogCustomFieldInformation

Parameters

Parameter Attribute DataType Description Allowed Values
LogFieldName Write String Field name to identify the custom field within the log file. Please note that the field name cannot contain spaces.
SourceType Write String The acceptable values for this property are: RequestHeader, ResponseHeader or ServerVariable (note that enhanced logging cannot log a server variable with a name that contains lower-case characters - to include a server variable in the event log just make sure that its name consists of all upper-case characters). RequestHeader, ResponseHeader, ServerVariable
SourceName Write String Name of the HTTP header or server variable (depending on the Source Type you selected) that contains a value that you want to log.

Description

The xWebSite 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 here for all open issues.

Examples

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_xWebSite_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 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                  = 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 xWebSite resources to copy the website content and configure the website.

Configuration Sample_xWebSite_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 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'
        }
    }
}

Example 3

configuration Sample_xWebSite_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 xWebAdministration, 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
        xWebSite 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
        xWebSite NewWebsite
        {
            Ensure          = 'Present'
            Name            = $WebSiteName
            SiteId       = $SiteId
            State           = 'Started'
            ServerAutoStart = $true
            PhysicalPath    = $DestinationPath
            DependsOn       = '[File]WebContent'
        }
    }
}

Example 4

Configuration Sample_xWebSite_NewWebsiteFromConfigurationData
{
    # Import the module that defines custom resources
    Import-DscResource -Module xWebAdministration, 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_xWebSite_Default)
        xWebSite 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
        xWebSite 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_xWebSite_RemoveDefault
{
    param
    (
        # Target nodes to apply the configuration
        [String[]] $NodeName = 'localhost'
    )

    # Import the module that defines custom resources
    Import-DscResource -Module xWebAdministration, PSDesiredStateConfiguration

    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'
            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_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 7

configuration Sample_xWebSite_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 xWebAdministration, 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
        xWebSite 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
        xWebSite NewWebsite
        {
            Ensure          = "Present"
            Name            = $WebSiteName
            State           = "Started"
            PhysicalPath    = $DestinationPath
            DependsOn       = "[File]WebContent"
            BindingInfo     = MSFT_xWebBindingInformation
            {
                Protocol              = 'https'
                Port                  = '443'
                CertificateStoreName  = 'MY'
                CertificateThumbprint = 'BB84DE3EC423DDDE90C08AB3C5A828692089493C'
                HostName              = $WebSiteName
                IPAddress             = '*'
                SSLFlags              = '1'
            }
        }
    }
}

WebAdministrationDsc Module

Clone this wiki locally