POSH-Oceanstor

1.0.2

Public/Remove-DMCifsShare.ps1

<#
.SYNOPSIS
    Removes an OceanStor CIFS share.
 
.DESCRIPTION
    Deletes an existing CIFS share by name, optionally scoped to a vStore.
    The share name is validated against existing OceanStor CIFS shares before the delete request is sent. The cmdlet supports -WhatIf and -Confirm.
 
    Accepts multiple shares from the pipeline by property name. Each share is resolved and removed
    independently: a failure (e.g. an invalid/ambiguous name, or a REST error) is reported as a
    non-terminating error and does not stop the remaining shares from being processed.
 
.PARAMETER WebSession
    Optional session object returned by Connect-deviceManager. When omitted, the module's cached $script:CurrentOceanstorSession session is used.
 
.PARAMETER ShareName
    Name of the CIFS share to remove. The name is validated against existing OceanStor CIFS shares.
 
.PARAMETER VstoreId
    Optional vStore ID used to scope the CIFS share removal operation.
 
.INPUTS
    System.Management.Automation.PSCustomObject
 
.OUTPUTS
    System.Management.Automation.PSCustomObject
    Returns the OceanStor API error object.
 
.EXAMPLE
    PS> Remove-DMCifsShare -ShareName 'share01' -WhatIf
 
    Shows what would happen if share01 were removed.
 
.NOTES
    Filename: Remove-DMCifsShare.ps1
#>
function Remove-DMCifsShare {
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]

    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    param(
        [Parameter(ValueFromPipelineByPropertyName = $true)]
        [pscustomobject]$WebSession,

        [Parameter(Mandatory = $true, Position = 0, ValueFromPipelineByPropertyName = $true)]
        [Alias('Name')]
        [ValidateNotNullOrEmpty()]
        [ArgumentCompleter({
                param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
                $session = if ($fakeBoundParameters.ContainsKey('WebSession')) {
                    $fakeBoundParameters.WebSession
                }
                else {
                    $script:CurrentOceanstorSession
                }
                (Get-DMShare -WebSession $session -ShareType CIFS).Name |
                    Sort-Object -Unique | Where-Object { $_ -like "$wordToComplete*" }
            })]
        [string]$ShareName,

        [string]$VstoreId
    )

    process {
        try {
            $session = if ($WebSession) {
                $WebSession
            }
            else {
                $script:CurrentOceanstorSession
            }

            $shares = @(Get-DMShare -WebSession $session -ShareType CIFS)
            $matchingItems = @($shares | Where-Object Name -EQ $ShareName)
            if ($matchingItems.Count -eq 0) {
                throw "Invalid ShareName. Valid values are: $($shares.Name -join ', ')"
            }
            if ($matchingItems.Count -gt 1) {
                throw "ShareName is ambiguous because more than one CIFS share is named '$ShareName'."
            }
            $share = $matchingItems[0]

            $resource = "CIFSSHARE/$($share.Id)"
            if ($VstoreId) {
                $resource += "?vstoreId=$VstoreId"
            }

            if ($PSCmdlet.ShouldProcess($ShareName, 'Remove CIFS share')) {
                $response = Invoke-DeviceManager -WebSession $session -Method 'DELETE' -Resource $resource
                $response = $response | Assert-DMApiSuccess
                return $response.error
            }
        }
        catch {
            $PSCmdlet.WriteError($_)
        }
    }
}