xActiveDirectory: Add Auto-Generated 'about_<DSCResource>.help.txt' F…

…iles for all Resources (#405) - Changes to xActiveDirectory - Added 'about_\<DSCResource\>.help.txt' file to all resources (issue #404).
dsccommunity · Jul 2, 2019 · b09ace8 · b09ace8
1 parent 9c0dc86
commit b09ace8
Show file tree

Hide file tree

Showing 20 changed files with 2,587 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 - Changes to xActiveDirectory
   - Added a Requirements section to every DSC resource README with the bullet point stating "Target machine must be running Windows Server 2008 R2 or later" ([issue #399](https://github.com/PowerShell/xActiveDirectory/pull/399)).
+  - Added 'about_\<DSCResource\>.help.txt' file to all resources ([issue #404](https://github.com/PowerShell/xActiveDirectory/pull/404)).
 - Changes to xADManagedServiceAccount
   - Added a requirement to README stating "Group Managed Service Accounts need at least one Windows Server 2012 Domain Controller" ([issue #399](https://github.com/PowerShell/xActiveDirectory/pull/399)).
 

diff --git a/DSCResources/MSFT_xADComputer/en-US/about_xADComputer.help.txt b/DSCResources/MSFT_xADComputer/en-US/about_xADComputer.help.txt
@@ -0,0 +1,218 @@
+.NAME
+    xADComputer
+
+.DESCRIPTION
+    The xADComputer DSC resource will manage computer accounts within Active Directory.
+    This resource can be used to provision a computer account before the computer is
+    added to the domain. These pre-created computer objects can be used with offline
+    domain join, unsecure domain Join and RODC domain join scenarios.
+
+    >**Note:** An Offline Domain Join (ODJ) request file will only be created
+    >when a computer account is first created in the domain. Setting an Offline
+    >Domain Join (ODJ) Request file path for a configuration that updates a
+    >computer account that already exists, or restore it from the recycle bin
+    >will not cause the Offline Domain Join (ODJ) request file to be created.
+
+    ## Requirements
+
+    * Target machine must be running Windows Server 2008 R2 or later.
+
+.PARAMETER ComputerName
+    Key - String
+    Specifies the name of the Active Directory computer account to manage. You can identify a computer by its distinguished name, GUID, security identifier (SID) or Security Accounts Manager (SAM) account name.
+
+.PARAMETER Location
+    Write - String
+    Specifies the location of the computer, such as an office number.
+
+.PARAMETER DnsHostName
+    Write - String
+    Specifies the fully qualified domain name (FQDN) of the computer account.
+
+.PARAMETER ServicePrincipalNames
+    Write - String
+    Specifies the service principal names for the computer account.
+
+.PARAMETER UserPrincipalName
+    Write - String
+    Specifies the UPN assigned to the computer account.
+
+.PARAMETER DisplayName
+    Write - String
+    Specifies the display name of the computer account.
+
+.PARAMETER Path
+    Write - String
+    Specifies the X.500 path of the Organizational Unit (OU) or container where the computer is located.
+
+.PARAMETER Description
+    Write - String
+    Specifies a description of the computer account.
+
+.PARAMETER Enabled
+    Write - Boolean
+    DEPRECATED - DO NOT USE. Please see the parameter EnabledOnCreation in this resource, and the resource xADObjectEnabledState on how to enforce the Enabled property. This parameter no longer sets or enforces the Enabled property. If this parameter is used then a warning message will be outputted saying that the Enabled parameter has been deprecated.
+
+.PARAMETER Manager
+    Write - String
+    Specifies the user or group Distinguished Name that manages the computer account. Valid values are the user's or group's DistinguishedName, ObjectGUID, SID or SamAccountName.
+
+.PARAMETER DomainController
+    Write - String
+    Specifies the Active Directory Domain Services instance to connect to perform the task.
+
+.PARAMETER DomainAdministratorCredential
+    Write - String
+    Specifies the user account credentials to use to perform the task.
+
+.PARAMETER RequestFile
+    Write - String
+    Specifies the full path to the Offline Domain Join Request file to create.
+
+.PARAMETER Ensure
+    Write - String
+    Allowed values: Present,  Absent
+    Specifies whether the computer account is present or absent. Valid values are 'Present' and 'Absent'. The default is 'Present'.
+
+.PARAMETER RestoreFromRecycleBin
+    Write - Boolean
+    Try to restore the computer account from the recycle bin before creating a new one.
+
+.PARAMETER EnabledOnCreation
+    Write - Boolean
+    Specifies if the computer account is created enabled or disabled. By default the Enabled property of the computer account will be set to the default value of the cmdlet New-ADComputer. This property is ignored if the parameter RequestFile is specified in the same configuration. This parameter does not enforce the property Enabled. To enforce the property Enabled see the resource xADObjectEnabledState.
+
+.PARAMETER DistinguishedName
+    Read - String
+    Returns the X.500 path of the computer object
+
+.PARAMETER SID
+    Read - String
+    Returns the security identifier of the computer object
+
+.PARAMETER SamAccountName
+    Read - String
+    Returns the security identifier of the computer object
+
+.EXAMPLE 1
+
+This configuration will create two Active Directory computer accounts
+enabled. The property Enabled will not be enforced in either case.
+
+Configuration AddComputerAccount_Config
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.PSCredential]
+        $DomainAdministratorCredential
+    )
+
+    Import-DscResource -ModuleName xActiveDirectory
+
+    node localhost
+    {
+        xADComputer 'CreateEnabled_SQL01'
+        {
+            ComputerName = 'SQL01'
+        }
+
+        xADComputer 'CreateEnabled_SQL02'
+        {
+            ComputerName      = 'SQL02'
+            EnabledOnCreation = $true
+        }
+    }
+}
+
+.EXAMPLE 2
+
+This configuration will create an Active Directory computer account
+disabled. The property Enabled will not be enforced.
+
+Configuration AddComputerAccountDisabled_Config
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.PSCredential]
+        $DomainAdministratorCredential
+    )
+
+    Import-DscResource -ModuleName xActiveDirectory
+
+    node localhost
+    {
+        xADComputer 'CreateDisabled'
+        {
+            ComputerName      = 'CLU_CNO01'
+            EnabledOnCreation = $false
+        }
+    }
+}
+
+.EXAMPLE 3
+
+This configuration will create an Active Directory computer account
+on the specified domain controller and in the specific organizational
+unit.
+
+Configuration AddComputerAccountSpecificPath_Config
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.PSCredential]
+        $DomainAdministratorCredential
+    )
+
+    Import-DscResource -ModuleName xActiveDirectory
+
+    node localhost
+    {
+        xADComputer 'CreateComputerAccount'
+        {
+            DomainController              = 'DC01'
+            ComputerName                  = 'SQL01'
+            Path                          = 'OU=Servers,DC=contoso,DC=com'
+            DomainAdministratorCredential = $DomainAdministratorCredential
+        }
+    }
+}
+
+.EXAMPLE 4
+
+This configuration will create an Active Directory computer account
+on the specified domain controller and in the specific organizational
+unit. After the account is create an Offline Domain Join Request file
+is created to the specified path.
+
+Configuration AddComputerAccountAndCreateODJRequest_Config
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.PSCredential]
+        $DomainAdministratorCredential
+    )
+
+    Import-DscResource -ModuleName xActiveDirectory
+
+    node localhost
+    {
+        xADComputer 'CreateComputerAccount'
+        {
+            DomainController              = 'DC01'
+            ComputerName                  = 'NANO-200'
+            Path                          = 'OU=Servers,DC=contoso,DC=com'
+            RequestFile                   = 'D:\ODJFiles\NANO-200.txt'
+            DomainAdministratorCredential = $DomainAdministratorCredential
+        }
+    }
+}
+
+