Public/cmdlet-functions.ps1
|
function Get-MVPackage { <# .SYNOPSIS List the packages in the current library. .DESCRIPTION The Get-MVPackage cmdlet lists the packages in the current library. It only works if invoked from a library root directory. Without parameters, it lists all packages. Otherwise, it lists packages matching the names provided. Matching is case-insensitive. Invalid package names passed in this parameter are ignored. .EXAMPLE Get-MVPackage This lists all packages. .EXAMPLE Get-MVPackage MyAwesomePackage This lists a package called MyAwesomePackage, if it is available in the current library. #> [CmdletBinding()] [OutputType([MVPackage[]])] Param ( # Specifies names of packages that this cmdlet lists. # Wildcard patterns are not allowed. Names are # case-insensitive. [Parameter( Mandatory = $false, Position = 0, ValueFromRemainingArguments = $true )] [string[]] $Name ) try { [MVLibrary]::TestCurrentDirectory() If ($Name.Count -eq 1) { return [MVLibrary]::GetPackage($Name[0]) } return [MVLibrary]::GetPackages($Name) } catch { $PSCmdlet.WriteError([MVLibrary]::CmdletError($_)) } } function New-MVPackage { <# .SYNOPSIS Create a new package in the current library. .DESCRIPTION The New-MVPackage cmdlet creates a new package in the current library. It only works if invoked from a library root directory. It checks if a package with the supplied name already exists. If not, it creates a directory with that name under the packages directory of the library. If the -HasCustomUI parameter is provided, it creates a directory called CustomUI under the package directory, and creates an Office Open XML custom ui manifest file in it called customUI.xml. .EXAMPLE New-MVPackage NewPackage1 This creates a new package without a custom ui subdirectory. .EXAMPLE New-MVPackage NewPackage1 -HasCustomUI This creates a new package with a custom ui subdirectory. #> [CmdletBinding()] [OutputType('MVPackage')] param ( # Specifies the name of the new package. [Parameter(Mandatory = $true, Position = 0)] [string] $Name, # Causes the CustomUI directory and file # to be created. [Parameter(Position = 1)] [switch] $HasCustomUI ) try { [MVLibrary]::TestCurrentDirectory() if ("" -eq $Name) { Write-Error "Package name must be specifed." -ErrorAction Stop } $newPackage = [MVLibrary]::NewPackage($Name, $HasCustomUI) return $newPackage } catch { $PSCmdlet.WriteError([MVLibrary]::CmdletError($_)) } } function Remove-MVPackage { <# .SYNOPSIS Remove a package from the current library. .DESCRIPTION The Remove-MVPackage cmdlet removes a package from the current library. It only works if invoked from a library root directory. .EXAMPLE Remove-MVPackage OldPackage1 This removes a package called OldPackage1. #> [CmdletBinding()] param ( # This specifies the name of the package to remove. The name # is case-insensitive. [Parameter(Position = 0)] [string] $PackageName = "" ) try { [MVLibrary]::TestCurrentDirectory() if ("" -eq $PackageName) { Write-Error "Package name must be specifed." -ErrorAction Stop } [void] [MVLibrary]::RemovePackage($PackageName) } catch { $PSCmdlet.WriteError([MVLibrary]::CmdletError($_)) } } function Get-MVLibrary { <# .SYNOPSIS Get details of the current library. .DESCRIPTION The Get-MVLibrary cmdlet gets the properties of the current library. It only works if invoked from a library root directory. .EXAMPLE Get-MVLibrary This shows details of the current library. #> [CmdletBinding()] param() try { [MVLibrary]::GetProjectConfig() } catch { $PSCmdlet.WriteError([MVLibrary]::CmdletError($_)) } } function New-MVLibrary { <# .SYNOPSIS Create a new VBA macro library. .DESCRIPTION The New-MVLibrary cmdlet creates a new Microsoft Office VBA macro library, which will contain VBA macros created for a specific Microsoft Office application. Macros have to be grouped into packages. Currently, a library can contain macros for any one of: Microsoft Word, Excel and PowerPoint. The cmdlet creates the library directory, with two subdirectories called packages and out. It also creates a file called library.json, and a .gitignore file that ignores Microsoft Office temporary files and the out subdirectory. .EXAMPLE New-MVLibrary AwesomeLibrary This creates a Library directory named AwesomeLibrary under the current directory. #> [CmdletBinding()] [OutputType('MVLibrary')] param ( # This specifies the name of the new library. [Parameter(Mandatory = $true, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Name, # This specifies the Microsoft Office application that # hosts the VBA macros in this library. Currently # supported values are Word, Excel and PowerPoint. # Case insensitive. [Parameter(Mandatory = $true, Position = 1)] [ValidateScript({ [MVLibrary]::TestOfficeApplication($_) })] [string] $Application ) try { [MVLibrary]::Create($Name, $Application) } catch { $PSCmdlet.WriteError([MVLibrary]::CmdletError($_)) } } function Initialize-MVLibrary { <# .SYNOPSIS Initialize a VBA macro library in the current directory. .DESCRIPTION The Initialize-MVLibrary cmdlet sets up a new Microsoft Office VBA macro library, which will contain VBA macros created for a specific Microsoft Office application, in the current directory. Currently, a library can contain macros for any one of: Microsoft Word, Excel and PowerPoint. The cmdlet creates two subdirectories called packages and out, if they are not already present. It also creates a file called library.json, and a .gitignore file that ignores Microsoft Office temporary files and the out subdirectory. If a .gitignore file is already present, it is appended to. .EXAMPLE New-MVLibrary AwesomeLibrary This creates a Library directory named AwesomeLibrary under the current directory. #> [CmdletBinding()] [OutputType('MVLibrary')] param ( # This specifies the name of the new library. [Parameter(Mandatory = $true, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Name, # This specifies the Microsoft Office application that # hosts the VBA macros in this library. Currently # supported values are Word, Excel and PowerPoint. # Case insensitive. [Parameter(Mandatory = $true, Position = 1)] [ValidateScript({ [MVLibrary]::TestOfficeApplication($_) })] [string] $Application ) try { [MVLibrary]::Init($Name, $Application) } catch { $PSCmdlet.WriteError([MVLibrary]::CmdletError($_)) } } function Build-MVLibrary { <# .SYNOPSIS Build a Microsoft Office document or add-in from the current library. .DESCRIPTION The Build-MVLibrary cmdlet builds a Microsoft Office document or add-in from the current library. It only works if invoked from a library root directory. The actual file built will depend on the Application property of the library. In any case, the file will contain the combined macros and custom UI elements from the selected packages. By default, macros and custom UI elements of all packages in the library are selected. The -PackageNames parameter allows one or more packages to be selected specifically if all are not needed. Invalid package names passed in this parameter are ignored. The final file will be placed in the out subdirectory of the library. .EXAMPLE Build-MVLibrary AllMacros AddIn This builds an application-specific add-in file that contains all packages in the library. .EXAMPLE Build-MVLibrary AllMacros Document Lucky1,Lucky2 This builds an application-specific document file that contains the packages Lucky1 and Lucky2. #> [CmdletBinding()] [OutputType('MVLibrary')] param ( # This specifies the name of the document or add-in # file that will be built from packages in this # library. It should be a file name without an # extension. [Parameter(Mandatory = $true, Position = 0)] [ValidateNotNullOrEmpty()] [string] $OutFileName, [Parameter(Mandatory = $false, Position = 1)] # This specifies the kind of output file to build. # Valid choices are AddIn or Document. [ValidateSet('AddIn', 'Document')] [string] $BuildType = 'AddIn', # This specifies the packages that will be built # into the output file. Not specifying this will # cause all the packages to be built it. Package # names are case-insensitive. [Parameter( Mandatory = $false, Position = 2, ValueFromRemainingArguments = $true )] [string[]] $PackageNames ) try { [MVLibrary]::TestCurrentDirectory() $buildPackages = [MVLibrary]::GetPackages($PackageNames) if ($buildPackages.Count -eq 0) { Write-Error "No valid packages selected for build." -ErrorAction Stop } [MVLibrary]::Build($OutFileName, $BuildType, $buildPackages) } catch { $PSCmdlet.WriteError([MVLibrary]::CmdletError($_)) } } |