1.    [File System] Open Explorer window for Default Web Site's home directory

2.    [File System] Open Explorer window for Default Web Site's home directory using "DirectoryName" property

3.    [File System] Create File and set file content programmatically

4.    [File System] Set "Deny" for administrator user account for 'iisstart.htm' file and grant access permission for NTAccount

5.    [Application Pool] Get the list of application pools

6.    [Application Pool] Create a new pool

NOTE: New-AppPool cannot use full path name such as “iis:\appPools\demoAppPool” like other user-friendly-named cmdlets

7.    [Application Pool] Rename an Application Pool

8.    [Application Pool] Remove an Application Pool

9.    [Application Pool] Stop/Start/Recycle Application Pool

10.[Application Pool] Get the current status of Application Pool

11.[Application Pool] Get the list of application which is belonged to an Application Pool

12.[Application Pool] Get Application Pool Default Settings

logEventOnRecyle property value shows number value, which is not human-readable. You can get the text enum value by querying the specific property instead such as shown in the following:

13.[Application Pool] Set Application Pool Default Settings

Case1: Setting queueLength, which is “property” type

Case2: Setting schedule, which is “element” type (shown as “Specific Times” in UI)

14.[Application Pool] Get configuration settings for a specific application pool

15.[Application Pool] Set configuration settings for a specific application pool

Case1: Setting logEventOnRecycle, which is “enum property” type

NOTE: The value could be set with "Time" in the next version instead of 1 for the above example

16.[Application Pool] Get the list of application pools

17.[Sites] Create a new Web Site

Case1: Create web site with single binding

Case2: Create web site with multiple binding and specific id

18.[Sites] Set bindings

Case1: Create SSL Binding (127.0.0.1!443)

Case2: Set 'Bindings' property with multiple binding information including the SSL binding which was created above.

NOTE: you can also use set-webconfiguration, set-webconfiguration or add-webconfigurationProperty.

Case3: Change a certain value of existing 'Bindings' property using other task-based  cmdlet.

Case4: Removing binding information using other task-based  cmdlet.

Or, you can use Remove-WebConfigurationProperty

Case5: Clear all the binding information of a certain web site

NOTE: you can also use clear-itemproperty instead:

19.[Sites] Rename an Web Site

20.[Sites] Remove an Web Site

21.[Sites] Stop/Start/Restart Web Site

22.[Sites] Get the current status of Web Site

23.[Sites] Get Web Site Defaults Settings

24.[Sites] Set Web Site Default Settings

Case1: Setting connectionTimeout

25.[Sites] Get configuration settings for a specific web site

26.[Sites] Set configuration settings for a specific web site

Case1: Setting maxLogFiles

If you are trying to change basic properties, you could also use set-itemProperty as shown in the following:

Case2: 'Application Pool' property

Case3: 'Physical Path' property

Case4: 'username' property

Case5: 'password' property

27.[Sites] Set Failed Request Tracing for a specific web site

Case1: Enable Freb for a specific web site with setting maxLogFiles and directory

Case2: Disable Freb for a specific web site

Case3: Clear Freb data for a specific web site

If you use Enable-Freb, it creates following default setting of Freb settings for the specified sites. We can clear them by this way.

28.[Management] Read default feature Delegation settings

Case1: Dump all sectionGroups

Case2: Dump specific sectionGroup such as "system.applicationHost"

Case3: Dump all sections under "/" group

NOTE: You will see empty value because IIS configuration system does not have section under "root" level by default

Case4: Dump all sections under specific sectionGroup such as "system.webServer"

NOTE: Now you can see the default override mode for "ASP" config section is deny, which means we can configure ASP related properties only for 'server' level

29.[Management] Add/Remove customized IIS config section

Case1: Add "myGroup" sectiongroup under root

Case2: Add "mySection" section under the myGroup sectiongroup which was created above

Case3: Set OverrideModeDefault for the newly created section, "mySection"

Case4: Set AllowDefinition for the newly created section, "mySection"

Case5: Set AllowLocation for the newly created section, "mySection"

Case6: Remove the "mySection" section which were created above

Case7: Remove the "myGroup" sectiongroup which were created above

30.[Management] Configure Feature Delegation related settings

NOTE: Before changing delegation setting of a config section, you would need to remove previously configured properties and elements of the section and re-configure them again after the delegation setting is updated.

This is an example of how to remove ASP sections using clear-webconfiguration cmdlet:

Case1: Read the current Delegation setting of ASP feature for 'server' level

NOTE: The value "inherit" means it uses the default override mode and it is actually "Deny" in the default IIS configuration

Case2: Set "Read-Write" for ASP feature for 'server' level

Case3: Set "Not Delegated" for ASP feature for 'server' level

NOTE: "Not Delegated" task is only applicable to IIS UI world. Please use "Read Only" which is explained below.

Case4: Set "Read Only" for ASP feature for 'server' level

Case5: Set "Reset to Inherited" for ASP feature for 'server' level

Case6: Change Delegation settings for 'site' level

Case7: Change Delegation settings for 'site' level using location

31.[IIS] Configure Clasic ASP properties

Case1: Read all ASP settings from 'server' level

Case2: Read all ASP settings from 'web site' level such as "Default Web Site"

Case3: Read all ASP settings from 'web application' level such as "DemoApplication "

Case4: Read all ASP settings from 'file' level which is under an Web Site

Case5: Write an ASP setting, keepSessionIdSecure, for 'server' level

Case6: Write an ASP setting, keepSessionIdSecure, for 'site' level

Case5: Write an ASP setting, keepSessionIdSecure, for 'file' level which is under an Web Site

32.[IIS] Configure Authentication properties

Case1: List all of authentications and from 'server' level

Case2: List all of authentications and from 'site' level

NOTE: You can also get from other levels adjusting the value -PSPath and -Location parameter values

Case3: Get all of Anonymous authentication properties from 'server' level

NOTE: You can also get from other levels adjusting the value -PSPath and -Location parameter values

Case4: Change userName property for Anonymous authentication properties from 'server' level

NOTE: You can also set for other levels adjusting the value -PSPath and -Location parameter values

33.[IIS] Configure Module elements and properties which are configured in globalModules section

Case1: List all native modules

Case2: Add a new native modue at the bottom index of the existing modules

Case3: Add a new native modue at the top index of the existing modules

Case4: Remove a native modue with a number index value

Case5: Remove a native modue with a hashtable index value

Case6: Get the attributes for a specific module

Case7: Change an attribute value for a specific module

34.[IIS] Configure Module elements and properties

Case1: Enable/Disable a native modue

Case2: Add a new managedModule

Case3: Disable module by removing the module element from the <modules> section

Case4: List all of enabled modules from 'server' level

Case5: Get the attributes for a specific module

Case6: Change an attribute value for a specific module

35.[IIS] Change order Module elements and Revert To Inherit for a site level

Case1: Move testmodule to bottom index

Case2: Revert To Inherit for 'site' level

36.[IIS] Get the list of worker processes and requests which is running on an Application Pool

I have started to learn IIS Native API (C++) and hope to share what I have learned. This blog is targeting for beginner programmers who want to develope IIS native module in C++ for the first time.

• Understanding Global Module/Module/Handler
• Quick reference of IIS Native API 
• IIS Core system 

Understanding Global Module/Module/Handler

In order to learn IIS native API, I tried to create a small module with various sample codes and found some cases of not working. In the explanation of the popular example module, I had learned that I needed to register the module onto both <globalModules> and <modules> section. And it worked with no question. 

• TIP
• My first module did not work because I complied the module as x86 version and wanted to make it run on amd64 bit machine. The problem was solved with compiling the module as 64 bit compilation)
• Another mistake happened when I used the full path of my module dll file which is created by Visual Studio without access permission. I had to give the access permission for the users group for the directory to solve the error such as "The Module DLL c:\work\IISNativeModule\Debug\MyModule.dll failed to load. The data is the error." which was shown in the event viewer.

My first module was to subscribe a single global level event such as GL_PRE_BEGIN_REQUEST and it worked in that way. And soon I realized the module works even though I removed the line of module from the <modules> section and I realized that if the module needs to subscribe only global level events, we don't need to register module onto <modules> section. This is how I learned the difference between module and global module in configuration wide.

I also tried to create another module which subscribes a single request level event such as RQ_EXECUTE_REQUEST_HANDLER. But this time, the module did not work even though I registered in the both <globalModules> and <modules> section.
I realized that actually I had made a handler module even though I thought I was making an ordinary module and I had to configure addional thing. Handler module is a special module which subscribes only the RQ_EXECUTE_REQUEST_HANDLER event. So, so the problem had to be solved by registering the module to <handlers> section.

But, I ran into another problem after I put my module, "TestModule", at the end of the value of modules attribute like this.

            <add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule, TestModule" resourceType="Either" requireAccess="Read" />

When I sent a request but the module was not invoked. And the problem was solved by changing the order of the module names like this.

            <add name="StaticFile" path="*" verb="*" modules=" TestModule ,StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />

That means, if there are multiple modules in a single handler item such as the above case, the previous modules can determine to make the next module run or not. And that's why my module was not picked up.

If you want to know more about this topic, refer to http://blogs.msdn.com/b/tmarq/archive/2007/08/30/iis-7-0-asp-net-pipelines-modules-handlers-and-preconditions.aspx.


Quick reference of IIS Native API

#include "stdafx.h"
#include <iostream>
using namespace std;
class IHttpContext
{
public:
 virtual void SetHttpRequest(int newValue) = 0; 
};
class IHttpEventProvider
{
public: 
 virtual IHttpContext* GetHttpContext() = 0; 
};
class HttpContext : IHttpEventProvider, IHttpContext
{
private:
 int* _pHttpRequest; 
public:
 HttpContext(int* pHttpRequest) : _pHttpRequest(pHttpRequest)
 {  
 }
 void SetHttpRequest(int newValue)
 {
  *_pHttpRequest = newValue;
 }
 IHttpContext* GetHttpContext()
 {
  return this;
 }
};
class HttpEventProvider: IHttpEventProvider
{
private:
 IHttpContext* _pHttpContext;
public:
 HttpEventProvider(IHttpContext* pHttpContext) : _pHttpContext(pHttpContext)
 {
 }
 
 virtual IHttpContext* GetHttpContext()
 {
  return _pHttpContext;
 }
};
class IModule
{
public:
 virtual void OnBeginRequest(IHttpEventProvider* provider) = 0; 
};
class Module : IModule
{
public:  
 void OnBeginRequest(IHttpEventProvider* pHttpEventProvider)
 { 
  IHttpContext* pHttpContext = pHttpEventProvider->GetHttpContext();
  pHttpContext->SetHttpRequest(3);  
 }
};
int _tmain(int argc, _TCHAR* argv[])
{
  // Step 1.
 // let's suppose httpRequest object is integer value and was created in the beginning. 
 // In actual world, the request object is created by http sys service for every request
 int httpRequest = 0; 
 cout << "Original Request: " << httpRequest << endl;
 // Step 2.
 // Now, IIS create the module object here to process the request. 
 //In the actual world, it was done by IIS's calling the IHttpModuleFactory::GetModule() method in each module .dll file.
 Module* pModule = new Module(); 
 // Step3.
 // After creating module object, IIS create HttpContext object with copying the httpRequest object inside it.
 HttpContext* pHttpContext = new HttpContext(&httpRequest);
 // Step4
 // And then, IIS creates httpEventProvider object, which will be used by the parameter object of the event handler function which is implemented in each module .dll file
 // As you can see here, the HttpContext object information copied to httpEventProvider object so that event handler can access the httpContext object 
 HttpEventProvider httpEventProvider((IHttpContext*) pHttpContext);
 // Step5
 // IIS creates state machine which invokes each deterministic request level events handler which is implemented in each module .dll file.
 // In actual world, there are global level event and non-deterministic request level events and they are fired outside of this state machine.
 IModule* pIModule;
 pIModule = (IModule*) pModule;  
 pIModule->OnBeginRequest((IHttpEventProvider *) pHttpContext);
 // Step6
 // Now the state machine is finished and then response object is passed to the http sys service and it transfer it to the client which started the httpRequest.
 cout << "Modified request by module: " << httpRequest << endl;
 
 // Step7
 // After all of the request is finished, the httpContext and module object is deleted to clean up
 delete pModule;
 delete pHttpContext;
 // In actual world, the event handler function can be implemented to support to handle asyncronous tasks but it wasn't explained here. I will explain it later.
 return 0;
}

IIS Powershell provider cmdlets require the config section path for the -filter parameter and the attribute names while getting/setting attribute value.

But it is not easy to memorize the full configuration path or attribute names for each config section.

So, I have created a utility method and a useful variable, such as $iis, and I put the full source code below so that you can customize if you want.

How to use this tool.

1. Start powershell.exe
2. Copy the below code and paste onto the powershell window to register the one utility function, Get-WebSchema, and to create a powershell variable, $iis with using the utility function
3. Try to run the Example Scenario 6~9 and you will see how you can use this tool with the IIS Powershell cmdlets. (NOTE: you will know you can use the auto-tab funcationality while using the $iis variable, which is what I told about getting config section names and attribute names dynamically as the following example:
   
   # Ex.) without using $iis variable; users should know the full config path and attribute name
   >> PS C:\Windows\system32> Get-WebConfigurationProperty -filter /system.webServer/security/authentication/basicAuthentication -name enabled
   
   # Ex.) using $iis variable; users can use the auto-tab to get the config section name string using $iis
   >> Get-WebConfigurationProperty -filter $iis.basicAuthentication -name $iis.basicAuthentication._enabled
   

####  Copy and paste from here!!!
#
#     -------------------------- EXAMPLE 1 --------------------------
#     C:\> Get-WebSchema -list
#     This command retrieves the list of schema files that are available.
#
#     -------------------------- EXAMPLE 2 --------------------------
#     C:\> Get-WebSchema -list -fileName "$env:windir\system32\inetsrv\config\schema\IIS_schema.xml"
#     This command retrieves the list of sections that are available for IIS_Schema.xml file.
#
#     -------------------------- EXAMPLE 3 --------------------------
#     C:\> Get-WebSchema -list -fileName "$env:windir\system32\inetsrv\config\schema\IIS_schema.xml" -sectionName system.webServer/asp
#     This command retrieves an xml node object for the asp section in Iis_Schema.xml file.
#
#     -------------------------- EXAMPLE 4 --------------------------
#     C:\> Get-WebSchema -fileName "$env:windir\system32\inetsrv\config\schema\IIS_schema.xml" -sectionName system.webServer/asp
#     This command list all config information (Ie. attribute/method/element/collection) of the asp section
#
#     -------------------------- EXAMPLE 5 --------------------------
#     C:\> Get-WebSchema -fileName "$env:windir\system32\inetsrv\config\schema\IIS_schema.xml"
#     This command list all config information (Ie. attribute/method/element/collection) of the IIS_Schema file
#
#     -------------------------- EXAMPLE 6 --------------------------
#     C:\> $iis
#     This command will dump all available config sections
#
#     -------------------------- EXAMPLE 7 --------------------------
#     C:\> $iis.site
#     This command will return string value of the full config path such as system.applicationHost/sites/site
#
#     -------------------------- EXAMPLE 8 --------------------------
#     C:\> $iis.appSettings._file
#     This command will return string value of the attribute name, such as "file", of the appSettings config section.
#     (NOTE: for quick find attribute name, I put "_" string at the beginning of attribute name.
#     For the example, $iis.appSettings._<TAB> will show $iis.appSettings._file.

function global:Get-WebSchema()
{
    param(
        [string]$fileName=$null,
        [string]$sectionName=$null,
        [object]$nodeObject=$null,
        [switch]$list,
        [switch]$verbose
    )

    if ($list -and $sectionName -and -not $fileName)
    {
        throw $(Get-PSResourceString -BaseName 'ParameterBinderStrings' -ResourceId 'AmbiguousParameterSet')
    }

    if ($list -and $recurse)
    {
        throw $(Get-PSResourceString -BaseName 'ParameterBinderStrings' -ResourceId 'AmbiguousParameterSet')
    }

    if ($sectionName -and -not $fileName)
    {
        throw $(Get-PSResourceString -BaseName 'ParameterBinderStrings' -ResourceId 'AmbiguousParameterSet')
    }

    if ($list)
    {
        if ($sectionName)
        {
            [xml]$xml = Get-Content $filename
            $rootNode = $xml.get_documentElement()
            $rootNode.sectionSchema | ForEach-Object {
                $nodeObject = $_               
                if ($nodeObject.name.tolower() -eq $sectionName.tolower())
                {                 
                    $nodeObject
                }
            }            
        }
        else
        {
            if ($fileName)
            {
                [xml]$xml = Get-Content $filename
                $rootNode = $xml.get_documentElement()
                $rootNode.sectionSchema | ForEach-Object {
                    $sectionName = $_.name
                    $sectionName
                }          
            }
            else
            {
                Get-ChildItem "$env:windir\system32\inetsrv\config\schema" -filter *.xml | ForEach-Object {
                    $filePath = $_.fullname
                    $filePath
                }
            }
        }   
    }
    else
    {
        if (-not $fileName -and -not $nodeObject) {
            throw $($(Get-PSResourceString -BaseName 'ParameterBinderStrings' -ResourceId 'ParameterArgumentValidationErrorNullNotAllowed') -f $null,'fileName')
        }

        if (-not $nodeObject)
        {
            [xml]$xml = Get-Content $filename
            $rootNode = $xml.get_documentElement()
            $rootNode.sectionSchema | ForEach-Object {
                $nodeObject = $_
                if ((-not $sectionName) -or ($nodeObject.name.tolower() -eq $sectionName.tolower()))
                {
                    Get-WebSchema -nodeObject $_ -filename $fileName -sectionName $nodeObject.name -verbose:$verbose
                }
            }           
        }      
        else
        {
            ("element", "collection", "attribute", "method") | ForEach-Object {
                $type = $_.tostring()
                if ($nodeObject.$type -ne $null)
                {  
                    $nodeObject.$type | ForEach-Object {
                         $leafObject = $_
                         $output = new-object psobject
                         if ($type -eq "collection")
                         {
                             $name = $leafObject.addElement
                             if ($verbose)
                             {
                                 $name = "[name]"
                             }
                         }
                         else
                         {
                             $name = $leafObject.name
                         }                       

                         $ItemXPath = $null
                         if ($verbose)
                         {
                             $ItemXPath = ($sectionName+"//"+$name)
                         }
                         else
                         {
                             $ItemXPath = ($sectionName+"/"+$name)
                         }
                         add-member -in $output noteproperty ItemXPath $ItemXPath
                         add-member -in $output noteproperty Name $name
                         add-member -in $output noteproperty XmlObject $leafObject
                         add-member -in $output noteproperty Type $leafObject.toString()
                         add-member -in $output noteproperty ParentXPath $sectionName
                         $output

                         if ($type -eq "element" -or $type -eq "collection")
                         {
                             Get-WebSchema -nodeObject $_ -filename $fileName -sectionName $ItemXPath -verbose:$verbose
                         }
                    }
                }
            }
        }
    }
}

$global:iis = new-object psobject
(dir "$env:windir\system32\inetsrv\config\schema\*.xml") | sort -Descending | select FullName,Name | foreach {
  $file = $_.Name
  $filepath = $_.FullName
 
  $saved_section = $null
  $sectionName = $null  
  $sectionValue = $null   

  Get-WebSchema -fileName $filePath | where {$_.Type -eq "attribute"} | foreach {
    $sectionPath = $_.ParentXPath
    $attribute = $_.Name

    ##
    ## when a new section is found
    ##
    if ($saved_section -ne $sectionPath) {
 
      if ($sectionName -ne $null) 
      {
        ##
        ## Now that the $sectionvalue is made for a specific config section,
        ## let's add the unique $sectionName noteproperty with $sectionName value onto $iis object
        ##
        add-member -in $iis noteproperty $sectionName $sectionValue
      }

      ##
      ## Let's create a new $sectionValue with assigning a new sectionPath value
      ##
      $sectionValue = $sectionPath

      ##
      ## Let's get an unique $sectionName which was not used before
      ##
      $tokens = $sectionPath.split("/")
      $sectionName = $tokens[$tokens.length-1]

      if ($tokens.length -gt 1 -and $tokens[$tokens.length-1] -eq "add")
      {
        $sectionName = $tokens[$tokens.length-2] + "_" + $tokens[$tokens.length-1]
      }
     
      ##
      ## if existing one has the same section configPath, copy it to the $sectionValue and then remove existing one in order to append
      ##
      if ($iis.$sectionName -ne $null -and $iis.$sectionName -eq $sectionPath)
      {
        $sectionValue = $iis.$sectionName
        $iis = $iis | select * -exclude $sectionName
      }
     
      if ($iis.$sectionName -ne $null)
      {
        $i = 2;
        do
        {
          $temp = $sectionName + $i
          $i = $i + 1
        }
        while ($iis.$temp -ne $null)           
        $sectionName = $temp
      }

      # reset $saved_section variable with the new section path
      $saved_section = $sectionPath
    }

    ##
    ## Let's add all of the attributes as a child noteproperty onto the $sectionValue string object
    ##
    $sectionValue = $sectionValue | add-member -membertype noteproperty -name ("_"+$attribute) -value $attribute -passthru
  }

  if ($sectionName -ne $null)
  {
    ##
    ## Let's process the last $sectionValue after loop statement
    ##
    add-member -in $iis noteproperty $sectionName $sectionValue
  }
}

Summary:

In the last blog, I tried to explain the big picture for IIS native API. So, next thing is to make a real native module. Because IIS native api is huge, I will introduce one by one with some interesting topics and explain why I was interested in for the specific topic.

In this blog, I decided to make a small program with which I can replace the response body with a specific data so that I can learn how to use the IIS native API for manipulating the response data. As usual, I had to solve some issues and hope to share what I learned while solving the problem.

What I learned:

If you look at the attached code below, you will notice the following two lines, which was my first issue to solve.

//char szBuffer[BUFFERLENGTH];
//char szBuffer2[BUFFERLENGTH];  

Because I did not know what memory should be used to set the FromMemory.pBuffer pointer, I started with a stack memory which is used by local variable and I realize it does not work. I got bunch of 0 values or some garbage data.
And then I realize that IIS API requires the memory should be kept in the life cycle of the request and that's why the stack memory did not work. Also, I realize httpContext has AllocateRequestMemory() method and we can allocate a certain size of memory with using it and the memory is kept during the life cycle of the request. So, I got the answer how to fix the first issue.

And then I wanted to display some non-English string and I realize the non-English string, for example Unicode string, should be encoded in UTF8 so that IE can display the data correctly.

I used WriteEntityChunkByReference() API function to set response body with my own data because we can directly assign my data using the API.

One thing interesting regarding the function is we can set -1 to append the data to the existing response body data.

I used OnGlobalPreBeginRequest event handler here. Please refer to MSDN what the event handler means.  

I also added the line of "pHttpResponse->Clear();" but it does not meaningful in the OnGlobalPreBeginRequest event handler because the response body is actually already empty because the response body is not made yet in that stage.

How to test the source code:

1. Logon as local administrator's account onto a machine where IIS is installed

2. Create a Visual C++ project of "Class Library" to make a DLL.

3. Copy and paste the above code

4. Right-mouse click the "Source Files" folder and click "Add" context menu and then select "New Item..."

5. Choose "Module-Definition File (.def)" and create a new .def file and paste the following 3 lines (NOTE: the "mod_HelloWorld" was used here because my project is to create the mod_HelloWorld.dll file; you should use the name of the dll file which is created by your project instead of the "mod_HelloWorld"):

Conclusion:

Now, I hope you feel confident about how to use the WriteEntityChunkByReference API for manipulating the response body and how to handle non English string to make response body with using this simple module.

If you are not clear yet, please try to read the code carefully and try to update the code as you want. I realize the best way to learn programing is to do it by myself without other's help. IIS native API, however, is too huge to catch them easily but you will feel it is actually not that huge eventually. 

I will try to introduce more interesting topic in the next time.