IIS Site::CreateSite

  • Article

The CreateSite procedure creates an IIS Web or FTP site and provides the option to set permissions on file system directories for content and logging.

Arguments

Input argument Required Description

<contentDir>

Yes

A required node that specifies the content directory to create, plus the permissions to set on the directory.

<contentDir parentShare="">

Yes

The parent shared folder is the network accessible Universal Naming Convention (UNC) path of the directory in which the site content will be kept. This shared folder must be accessible from the MPF server.

<contentDir parentPath="">

Yes

This value is used to generate the Path property for the website. If the content is kept on a network shared folder instead of on a local drive, then parentShare will be a UNC path that is identical to parentShare. Otherwise it will be a local path.

<contentDir name="">

No

If this optional parameter is supplied, it will be the name of the content directory that is created for the site. Otherwise, the ServerComment of the site will be used as the directory name.

<contentDir><acl>

No

The optional <acl> parameter follows the acl format defined in the MPF File System Provider. The book Writing Secure Code recommends that permission granting be done by granting permissions to appropriate groups, then making users members of those groups rather than granting user permissions directly. A suggested <acl> is shown in the example below. This <acl> grants read permissions to MyReadersGroup, and admin permissions to MyAdminsGroup.

<logDir>

No

This optional node that specifies a log directory to create, plus the permissions to set on the directory. All attributes and the permissions are the same as <contentDir>, except for the optional inContent attribute.

<logDir inContent="">

No

If this attribute is present (the value does not matter,) the log directory will be created directly under the content directory and the parentShare and parentPath attributes will be ignored. If inContent is present and the name attribute is missing, the log directory name will default to logs.

<key>

Yes

This is a required node that specifies the metabase key.

<key path="">

No

The path is the IIS path of the metabase key. The path is required only in the root key node of the request. Child key nodes do not use path, and require name instead. This attribute is filled in on return for all keys. When creating a Web or FTP site, the provider will automatically choose a site number if the site number requested is "*" as shown in the example. On return, the path name will be filled in with the generated site number.

It is important to ensure path points to a valid, appropriate and trusted location. See the security note in IIS Provisioning Security Considerations for more details.

<key name="">

Yes

The name of the metabase key. The name is ignored in the root key node of the request, and mandatory in child key nodes. This attribute is filled in upon return for all keys.

<key type="">

No

(returned) The type attribute specifies the object type to be created.

<keys>

No

The optional keys node specifies any child keys which should be created. The <key name="root"> node is necessary for the website to function. Other keys may be created if desired.

SiteProperties

Yes

These properties are stored directly under the site key in the metabase. The minimum required properties and subkeys are shown in the XML example for this procedure, however, you can provide additional properties and subkeys if desired.

  • ServerComment - The name of the website as displayed in the Windows management UI.

  • ServerBindings - A multi-valued property containing IP address, port number, and host header name separated by colons. IP address may be zero-length to represent all unassigned. Host header may be zero-length. Port number is mandatory.

  • ServerAutoStart - Unless this optional value is 0, the site will start immediately upon creation. Defaults depends on the IIS installation, usually is 1. If the ServerState property is supplied, it overrides the start upon creation behavior of ServerAutoStart.

  • ServerState - This optional property is given special handling by the IIS Provider to ensure that the site state transitions to the supplied value by calling the appropriate Start, Stop, Pause, and Continue methods. An apparent bug in IIS 5.0 causes the Start method to fail when called immediately upon site creation, so it may be necessary to set this property as a separate step in for IIS 5.0 servers. See the SetProperties (ControlSite) method of IIS Provider API in this volume for more detail about the ServerState property.

  • AnonymousUserName - An optional string specifying the account for anonymous users. If not present, nothing is done, but IIS will use the default.

  • AnonymousUserPass - Required if AnonymousUserName is supplied.

  • LogExtFileFlags - An integer value. See IIS documentation for possible values.

  • LogFileDirectory - (ignored) Any value supplied for this property will be discarded and replaced with the directory specified in <logDir>.

<key name="root">

Yes

A required virtual directory within the Web site.

Root/properties

Yes

These properties are stored in the Root key which exists under the site key in the metabase. The minimum required properties are shown in the XML example for this procedure, however, you can provide additional properties if desired.

  • Path - (ignored) Any value supplied for this property will be discarded and replaced with the directory specified in <contentDir>.

  • UNCUserName - (optional) If the path is a UNC name, this user name will be used with the UNCPassword to access the UNC resource.

  • UNCPassword - (optional) Uses blank password if not supplied.

  • AuthFlags - (optional) Integer. See IIS documentation for legal values.

  • AppFriendlyName - (optional) string. Defaults to Default Application.

  • AppIsolated - (optional) integer. Uses IIS default.

  • AppPoolId - (optional) string. For IIS 6.0 only.

  • Create - (optional) Set to "1" to create the app pool if it does not exist. Default is "0".

Output Argument

The CreateSite procedure returns all path and name attributes of the request filled in.

Remarks

Example Process Steps

The following is an example of the steps you can follow when creating a website with the CreateSite procedure of the IIS Namespace:

  • Create the content folder and set its permissions.

  • Create the log files folder, if requested, and set its permissions.

  • Ensure the existence of an application pool, if supplied.

  • Create the website.

  • Set website properties.

  • Create the root virtual directory.

  • Create the application.

  • Set application isolation mode.

  • Add the application to the application pool if supplied.

  • The site will start or not depending on the ServerAutoStart and ServerState properties. See IIS Provider API in this volume for more detail.

Sample Code

Example XML Request

The following is an example of an XML request for the CreateSite procedure of the IIS Namespace:

<request> 
    <procedure> 
        <execute namespace="IIS Site" procedure="Create" 
         impersonate="1"> 
            <executeData> 
                <preferredDomainController>AD01.fabrikam.com 
                </preferredDomainController> 
                <contentDir parentShare="\\WEB01\wwwShare\test" 
                 parentPath="c:\inetpub\wwwroot\test"> 
                    <acl> 
                        <ace> 
                <!- Readers read and traverse all child directories -> 
                        <permission>FILE_TRAVERSE</permission> 
                        <permission>FILE_GENERIC_READ</permission> 
                        <permission>FILE_EXECUTE</permission> 
                        <mode>GRANT_ACCESS</mode> 
                        <inheritance>SUB_CONTAINERS_ONLY_INHERIT 
                        </inheritance> 
                        <trusteeType>TRUSTEE_IS_GROUP</trusteeType> 
                        <trusteeForm>TRUSTEE_IS_NAME</trusteeForm> 
                        <trustee>MACHINE_NAME\MyReadersGroup</trustee> 
                        </ace> 
                        <ace> 
                        <!- Readers read and execute files -> 
                        <permission>FILE_GENERIC_READ</permission> 
                        <permission>FILE_EXECUTE</permission> 
                        <mode>GRANT_ACCESS</mode> 
                        <inheritance>SUB_CONTAINERS_AND_OBJECTS_INHERIT 
                        </inheritance> 
                        <trusteeType>TRUSTEE_IS_GROUP</trusteeType> 
                        <trusteeForm>TRUSTEE_IS_NAME</trusteeForm> 
                        <trustee>MACHINE_NAME\MyReadersGroup 
                        </trustee> 
                        </ace> 
                        <ace> 
                        <!- <permission>FILE_ALL_ACCESS</permission> -> 
                        <permission>2032639</permission> 
                        <mode>GRANT_ACCESS</mode> 
                        <inheritance>SUB_CONTAINERS_AND_OBJECTS_INHERIT 
                        </inheritance> 
                        <trusteeType>TRUSTEE_IS_GROUP</trusteeType> 
                        <trusteeForm>TRUSTEE_IS_NAME</trusteeForm> 
                        <trustee>DOMAIN\MyAdminsGroup</trustee> 
                        </ace> 
                    </acl> 
                </contentDir> 
                <logDir parentShare="\\WEB01\wwwShare\testLogs" 
                 parentPath="c:\inetpub\wwwroot\testLogs"> 
                    <acl/> 
                </logDir> 
                <key path="IIS://WEB01/W3SVC/*" type="IIsWebServer"> 
                    <properties> 
                    <property name="ServerComment">www.fabrikam.com 
                    </property> 
                    <property name="ServerAutoStart">0</property> 
                    <property name="ServerBindings"> 
                        <values> 
                            <value>:8001:</value> 
                        </values> 
                    </property> 
                </properties> 
                <keys> 
                <key name="root" type="IIsWebVirtualDir"> 
                    <properties> 
                        <property name="AccessFlags">517</property> 
                        <property name="AppFriendlyName">Default 
                         Application</property> 
                        <property name="Path">c:\inetpub\wwwroot\test 
                        </property> 
                    </properties> 
                </key> 
                </keys> 
                </key> 
            </executeData> 
            <after source="executeData" destination="data"/> 
        </execute> 
    </procedure> 
</request>

Example XML Response

The following is an example of an XML response for the CreateSite procedure of the IIS Namespace:

<response> 
    <data> 
        <executeData> 
            <key path="IIS://WEB01/W3SVC/13837811" type="IIsWebServer" 
             name="13837811"> 
                <properties> 
                    <property name="ServerComment">www.fabrikam.com 
                    </property> 
                    <property name="ServerBindings"> 
                        <values> 
                            <value>:8001:</value> 
                        </values> 
                    </property> 
                </properties> 
                <keys> 
                    <key name="root" type="IIsWebVirtualDir" 
                     path="IIS://WEB01/W3SVC/13837811/root"> 
                        <properties> 
                          <property name="AccessFlags">517</property> 
                          <property name="AppFriendlyName">Default 
                           Application</property> 
                          <property name="Path">c:\inetpub\wwwroot\test 
                          </property> 
                        </properties> 
                    </key> 
                </keys> 
            </key> 
        </executeData> 
    </data> 
</response>

Applies To

IIS Site Namespace API for:

  • Hosted Messaging and Collaboration version 3.5

  • Hosted Messaging and Collaboration version 3.0

  • Windows-based Hosting version 4.5

  • Windows-based Hosting version 4.0

  • Windows-based Hosting version 3.5

  • Windows-based Hosting for Applications version 1.0

See also

Tasks

IIS Site::DeleteSite

Concepts

IIS Site::ModifySite