MegaBites-AI/Windows-powershell
0372
1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Diagnostics.CodeAnalysis;5using System.Management.Automation.Internal;6 7namespace System.Management.Automation.Provider8{9 #region ContainerCmdletProvider10 11 /// <summary>12 /// The base class for Cmdlet providers that expose a single level of items.13 /// </summary>14 /// <remarks>15 /// The ContainerCmdletProvider class is base class that a provider derives from16 /// to implement methods that allow17 /// the use of a set of core commands against the objects that the provider18 /// gives access to. By deriving from this class users can take advantage of19 /// all the features of the <see cref="ItemCmdletProvider"/> as well as20 /// globbing and the following commands when targeting this provider:21 /// get-childitem22 /// rename-item23 /// new-item24 /// remove-item25 /// set-location26 /// push-location27 /// pop-location28 /// get-location -stack29 /// </remarks>30 public abstract class ContainerCmdletProvider : ItemCmdletProvider31 {32 #region Internal methods33 34 /// <summary>35 /// Internal wrapper for the GetChildItems protected method. It is called instead36 /// of the protected method that is overridden by derived classes so that the37 /// context of the command can be set.38 /// </summary>39 /// <param name="path">40 /// The path (or name in a flat namespace) to the item from which to retrieve the children.41 /// </param>42 /// <param name="recurse">43 /// True if all children in a subtree should be retrieved, false if only a single44 /// level of children should be retrieved. This parameter should only be true for45 /// the NavigationCmdletProvider derived class.46 /// </param>47 /// <param name="depth">48 /// Limits the depth of recursion; uint.MaxValue performs full recursion.49 /// </param>50 /// <param name="context">51 /// The context under which this method is being called.52 /// </param>53 /// <returns>54 /// Nothing is returned, but all children should be written to the Write*Object or55 /// Write*Objects method.56 /// </returns>57 internal void GetChildItems(58 string path,59 bool recurse,60 uint depth,61 CmdletProviderContext context)62 {63 Context = context;64 65 // Call virtual method66 67 GetChildItems(path, recurse, depth);68 }69 70 /// <summary>71 /// Gives the provider to attach additional parameters to72 /// the get-childitem cmdlet.73 /// </summary>74 /// <param name="path">75 /// If the path was specified on the command line, this is the path76 /// to the item to get the dynamic parameters for.77 /// </param>78 /// <param name="recurse">79 /// True if all children in a subtree should be retrieved, false if only a single80 /// level of children should be retrieved. This parameter should only be true for81 /// the NavigationCmdletProvider derived class.82 /// </param>83 /// <param name="context">84 /// The context under which this method is being called.85 /// </param>86 /// <returns>87 /// Overrides of this method should return an object that has properties and fields decorated with88 /// parsing attributes similar to a cmdlet class or a89 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.90 ///91 /// The default implementation returns null. (no additional parameters)92 /// </returns>93 internal object GetChildItemsDynamicParameters(94 string path,95 bool recurse,96 CmdletProviderContext context)97 {98 Context = context;99 return GetChildItemsDynamicParameters(path, recurse);100 }101 102 /// <summary>103 /// Internal wrapper for the GetChildNames protected method. It is called instead104 /// of the protected method that is overridden by derived classes so that the105 /// context of the command can be set.106 /// </summary>107 /// <param name="path">108 /// The path to the item from which to retrieve the child names.109 /// </param>110 /// <param name="returnContainers">111 /// Determines if all containers should be returned or only those containers that match the112 /// filter(s).113 /// </param>114 /// <param name="context">115 /// The context under which this method is being called.116 /// </param>117 /// <returns>118 /// Nothing is returned, but all names should be written to the Write*Object or119 /// Write*Objects method.120 /// </returns>121 /// <remarks>122 /// The child names are the leaf portion of the path. Example, for the file system123 /// the name for the path c:\windows\system32\foo.dll would be foo.dll or for124 /// the directory c:\windows\system32 would be system32. For Active Directory the125 /// child names would be RDN values of the child objects of the container.126 /// </remarks>127 internal void GetChildNames(128 string path,129 ReturnContainers returnContainers,130 CmdletProviderContext context)131 {132 Context = context;133 134 // Call virtual method135 GetChildNames(path, returnContainers);136 }137 138 /// <summary>139 /// Gets a new provider-specific path and filter (if any) that corresponds to the given140 /// path.141 /// </summary>142 /// <param name="path">143 /// The path to the item. Unlike most other provider APIs, this path is likely to144 /// contain PowerShell wildcards.145 /// </param>146 /// <param name="filter">147 /// The provider-specific filter currently applied.148 /// </param>149 /// <param name="updatedPath">150 /// The new path to the item.151 /// </param>152 /// <param name="updatedFilter">153 /// The new filter.154 /// </param>155 /// <param name="context">156 /// The context under which this method is being called.157 /// </param>158 /// <returns>159 /// True if the path or filter were altered. False otherwise.160 /// </returns>161 /// <remarks>162 /// Providers override this method if they support a native filtering syntax that163 /// can offer performance improvements over wildcard matching done by the PowerShell164 /// engine.165 /// If the provider can handle a portion (or all) of the PowerShell wildcard with166 /// semantics equivalent to the PowerShell wildcard, it may adjust the path to exclude167 /// the PowerShell wildcard.168 /// If the provider can augment the PowerShell wildcard with an approximate filter (but169 /// not replace it entirely,) it may simply return a filter without modifying the path.170 /// In this situation, PowerShell's wildcarding will still be applied to a smaller result171 /// set, resulting in improved performance.172 ///173 /// The default implementation of this method leaves both Path and Filter unmodified.174 /// </remarks>175 [SuppressMessage("Microsoft.Design", "CA1045:DoNotPassTypesByReference", MessageId = "2#")]176 [SuppressMessage("Microsoft.Design", "CA1045:DoNotPassTypesByReference", MessageId = "3#")]177 internal virtual bool ConvertPath(178 string path,179 string filter,180 ref string updatedPath,181 ref string updatedFilter,182 CmdletProviderContext context)183 {184 Context = context;185 186 // Call virtual method187 return ConvertPath(path, filter, ref updatedPath, ref updatedFilter);188 }189 190 /// <summary>191 /// Gives the provider to attach additional parameters to192 /// the get-childitem -name cmdlet.193 /// </summary>194 /// <param name="path">195 /// If the path was specified on the command line, this is the path196 /// to the item to get the dynamic parameters for.197 /// </param>198 /// <param name="context">199 /// The context under which this method is being called.200 /// </param>201 /// <returns>202 /// Overrides of this method should return an object that has properties and fields decorated with203 /// parsing attributes similar to a cmdlet class or a204 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.205 ///206 /// The default implementation returns null. (no additional parameters)207 /// </returns>208 internal object GetChildNamesDynamicParameters(209 string path,210 CmdletProviderContext context)211 {212 Context = context;213 return GetChildNamesDynamicParameters(path);214 }215 216 /// <summary>217 /// Internal wrapper for the RenameItem protected method. It is called instead218 /// of the protected method that is overridden by derived classes so that the219 /// context of the command can be set.220 /// </summary>221 /// <param name="path">222 /// The path to the item to rename.223 /// </param>224 /// <param name="newName">225 /// The name to which the item should be renamed. This name should always be226 /// relative to the parent container.227 /// </param>228 /// <param name="context">229 /// The context under which this method is being called.230 /// </param>231 /// <returns>232 /// Nothing is returned, but all renamed items should be written to the Write*Object or233 /// Write*Objects.234 /// </returns>235 internal void RenameItem(236 string path,237 string newName,238 CmdletProviderContext context)239 {240 Context = context;241 242 // Call virtual method243 244 RenameItem(path, newName);245 }246 247 /// <summary>248 /// Gives the provider to attach additional parameters to249 /// the rename-item cmdlet.250 /// </summary>251 /// <param name="path">252 /// If the path was specified on the command line, this is the path253 /// to the item to get the dynamic parameters for.254 /// </param>255 /// <param name="newName">256 /// The name to which the item should be renamed. This name should always be257 /// relative to the parent container.258 /// </param>259 /// <param name="context">260 /// The context under which this method is being called.261 /// </param>262 /// <returns>263 /// An object that has properties and fields decorated with264 /// parsing attributes similar to a cmdlet class.265 /// </returns>266 internal object RenameItemDynamicParameters(267 string path,268 string newName,269 CmdletProviderContext context)270 {271 Context = context;272 return RenameItemDynamicParameters(path, newName);273 }274 275 /// <summary>276 /// Internal wrapper for the New protected method. It is called instead277 /// of the protected method that is overridden by derived classes so that the278 /// context of the command can be set.279 /// </summary>280 /// <param name="path">281 /// The path to the item to create.282 /// </param>283 /// <param name="type">284 /// The provider defined type of the item to create.285 /// </param>286 /// <param name="newItemValue">287 /// This is a provider specific type that the provider can use to create a new288 /// instance of an item at the specified path.289 /// </param>290 /// <param name="context">291 /// The context under which this method is being called.292 /// </param>293 /// <returns>294 /// Nothing is returned, but all new items should be written to the Write*Object or295 /// Write*Objects.296 /// </returns>297 internal void NewItem(298 string path,299 string type,300 object newItemValue,301 CmdletProviderContext context)302 {303 Context = context;304 305 // Call virtual method306 307 NewItem(path, type, newItemValue);308 }309 310 /// <summary>311 /// Gives the provider to attach additional parameters to312 /// the new-item cmdlet.313 /// </summary>314 /// <param name="path">315 /// If the path was specified on the command line, this is the path316 /// to the item to get the dynamic parameters for.317 /// </param>318 /// <param name="type">319 /// The provider defined type of the item to create.320 /// </param>321 /// <param name="newItemValue">322 /// This is a provider specific type that the provider can use to create a new323 /// instance of an item at the specified path.324 /// </param>325 /// <param name="context">326 /// The context under which this method is being called.327 /// </param>328 /// <returns>329 /// An object that has properties and fields decorated with330 /// parsing attributes similar to a cmdlet class.331 /// </returns>332 internal object NewItemDynamicParameters(333 string path,334 string type,335 object newItemValue,336 CmdletProviderContext context)337 {338 Context = context;339 return NewItemDynamicParameters(path, type, newItemValue);340 }341 342 /// <summary>343 /// Internal wrapper for the Remove protected method. It is called instead344 /// of the protected method that is overridden by derived classes so that the345 /// context of the command can be set.346 /// </summary>347 /// <param name="path">348 /// The path to the item to remove.349 /// </param>350 /// <param name="recurse">351 /// True if all children in a subtree should be removed, false if only a single352 /// level of children should be removed. This parameter should only be true for353 /// NavigationCmdletProvider and its derived classes.354 /// </param>355 /// <param name="context">356 /// The context under which this method is being called.357 /// </param>358 internal void RemoveItem(359 string path,360 bool recurse,361 CmdletProviderContext context)362 {363 Context = context;364 365 // Call virtual method366 367 RemoveItem(path, recurse);368 }369 370 /// <summary>371 /// Gives the provider to attach additional parameters to372 /// the remove-item cmdlet.373 /// </summary>374 /// <param name="path">375 /// If the path was specified on the command line, this is the path376 /// to the item to get the dynamic parameters for.377 /// </param>378 /// <param name="recurse">379 /// True if all children in a subtree should be removed, false if only a single380 /// level of children should be removed. This parameter should only be true for381 /// NavigationCmdletProvider and its derived classes.382 /// </param>383 /// <param name="context">384 /// The context under which this method is being called.385 /// </param>386 /// <returns>387 /// An object that has properties and fields decorated with388 /// parsing attributes similar to a cmdlet class.389 /// </returns>390 internal object RemoveItemDynamicParameters(391 string path,392 bool recurse,393 CmdletProviderContext context)394 {395 Context = context;396 return RemoveItemDynamicParameters(path, recurse);397 }398 399 /// <summary>400 /// Internal wrapper for the HasChildItems protected method. It is called instead401 /// of the protected method that is overridden by derived classes so that the402 /// context of the command can be set.403 /// </summary>404 /// <param name="path">405 /// The path to the item to see if it has children.406 /// </param>407 /// <param name="context">408 /// The context under which this method is being called.409 /// </param>410 /// <returns>411 /// True if the item has children, false otherwise.412 /// </returns>413 /// <remarks>414 /// For implementers of ContainerCmdletProvider classes and those derived from it,415 /// if a null or empty path is passed,416 /// the provider should consider any items in the data store to be children417 /// and return true.418 /// </remarks>419 internal bool HasChildItems(string path, CmdletProviderContext context)420 {421 Context = context;422 423 // Call virtual method424 425 return HasChildItems(path);426 }427 428 /// <summary>429 /// Internal wrapper for the Copy protected method. It is called instead430 /// of the protected method that is overridden by derived classes so that the431 /// context of the command can be set.432 /// </summary>433 /// <param name="path">434 /// The path of the item to copy.435 /// </param>436 /// <param name="copyPath">437 /// The path of the item to copy to.438 /// </param>439 /// <param name="recurse">440 /// Tells the provider to recurse sub-containers when copying.441 /// </param>442 /// <param name="context">443 /// The context under which this method is being called.444 /// </param>445 /// <returns>446 /// Nothing. All objects that are copied should be written to the Write*Object or447 /// Write*Objects methods.448 /// </returns>449 internal void CopyItem(450 string path,451 string copyPath,452 bool recurse,453 CmdletProviderContext context)454 {455 Context = context;456 457 // Call virtual method458 459 CopyItem(path, copyPath, recurse);460 }461 462 /// <summary>463 /// Gives the provider to attach additional parameters to464 /// the copy-item cmdlet.465 /// </summary>466 /// <param name="path">467 /// If the path was specified on the command line, this is the path468 /// to the item to get the dynamic parameters for.469 /// </param>470 /// <param name="destination">471 /// The path of the item to copy to.472 /// </param>473 /// <param name="recurse">474 /// Tells the provider to recurse sub-containers when copying.475 /// </param>476 /// <param name="context">477 /// The context under which this method is being called.478 /// </param>479 /// <returns>480 /// An object that has properties and fields decorated with481 /// parsing attributes similar to a cmdlet class.482 /// </returns>483 internal object CopyItemDynamicParameters(484 string path,485 string destination,486 bool recurse,487 CmdletProviderContext context)488 {489 Context = context;490 return CopyItemDynamicParameters(path, destination, recurse);491 }492 493 #endregion Internal members494 495 #region Protected methods496 497 /// <summary>498 /// Gets the children of the item at the specified path.499 /// </summary>500 /// <param name="path">501 /// The path (or name in a flat namespace) to the item from which to retrieve the children.502 /// </param>503 /// <param name="recurse">504 /// True if all children in a subtree should be retrieved, false if only a single505 /// level of children should be retrieved. This parameter should only be true for506 /// the NavigationCmdletProvider derived class.507 /// </param>508 /// <returns>509 /// Nothing is returned, but all objects should be written to the WriteItemObject method.510 /// </returns>511 /// <remarks>512 /// Providers override this method to give the user access to the provider objects using513 /// the get-childitem cmdlets.514 ///515 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>516 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those517 /// requirements by accessing the appropriate property from the base class.518 ///519 /// By default overrides of this method should not write objects that are generally hidden from520 /// the user unless the Force property is set to true. For instance, the FileSystem provider should521 /// not call WriteItemObject for hidden or system files unless the Force property is set to true.522 ///523 /// The provider implementation is responsible for preventing infinite recursion when there are524 /// circular links and the like. An appropriate terminating exception should be thrown if this525 /// situation occurs.526 ///527 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.528 /// </remarks>529 protected virtual void GetChildItems(530 string path,531 bool recurse)532 {533 using (PSTransactionManager.GetEngineProtectionScope())534 {535 throw536 PSTraceSource.NewNotSupportedException(537 SessionStateStrings.CmdletProvider_NotSupported);538 }539 }540 541 /// <summary>542 /// Gets the children of the item at the specified path.543 /// </summary>544 /// <param name="path">545 /// The path (or name in a flat namespace) to the item from which to retrieve the children.546 /// </param>547 /// <param name="recurse">548 /// True if all children in a subtree should be retrieved, false if only a single549 /// level of children should be retrieved. This parameter should only be true for550 /// the NavigationCmdletProvider derived class.551 /// </param>552 /// <param name="depth">553 /// Limits the depth of recursion; uint.MaxValue performs full recursion.554 /// </param>555 /// <returns>556 /// Nothing is returned, but all objects should be written to the WriteItemObject method.557 /// </returns>558 /// <remarks>559 /// Providers override this method to give the user access to the provider objects using560 /// the get-childitem cmdlets.561 ///562 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>563 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those564 /// requirements by accessing the appropriate property from the base class.565 ///566 /// By default overrides of this method should not write objects that are generally hidden from567 /// the user unless the Force property is set to true. For instance, the FileSystem provider should568 /// not call WriteItemObject for hidden or system files unless the Force property is set to true.569 ///570 /// The provider implementation is responsible for preventing infinite recursion when there are571 /// circular links and the like. An appropriate terminating exception should be thrown if this572 /// situation occurs.573 ///574 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.575 /// </remarks>576 protected virtual void GetChildItems(577 string path,578 bool recurse,579 uint depth)580 {581 using (PSTransactionManager.GetEngineProtectionScope())582 {583 if (depth == uint.MaxValue)584 {585 this.GetChildItems(path, recurse);586 }587 else588 {589 throw590 PSTraceSource.NewNotSupportedException(591 SessionStateStrings.CmdletProvider_NotSupportedRecursionDepth);592 }593 }594 }595 596 /// <summary>597 /// Gives the provider an opportunity to attach additional parameters to598 /// the get-childitem cmdlet.599 /// </summary>600 /// <param name="path">601 /// If the path was specified on the command line, this is the path602 /// to the item to get the dynamic parameters for.603 /// </param>604 /// <param name="recurse">605 /// True if all children in a subtree should be retrieved, false if only a single606 /// level of children should be retrieved. This parameter should only be true for607 /// the NavigationCmdletProvider derived class.608 /// </param>609 /// <returns>610 /// Overrides of this method should return an object that has properties and fields decorated with611 /// parsing attributes similar to a cmdlet class or a612 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.613 ///614 /// The default implementation returns null. (no additional parameters)615 /// </returns>616 protected virtual object GetChildItemsDynamicParameters(string path, bool recurse)617 {618 using (PSTransactionManager.GetEngineProtectionScope())619 {620 return null;621 }622 }623 624 /// <summary>625 /// Gets names of the children of the specified path.626 /// </summary>627 /// <param name="path">628 /// The path to the item from which to retrieve the child names.629 /// </param>630 /// <param name="returnContainers">631 /// Determines if all containers should be returned or only those containers that match the632 /// filter(s).633 /// </param>634 /// <returns>635 /// Nothing is returned, but all objects should be written to the WriteItemObject method.636 /// </returns>637 /// <remarks>638 /// Providers override this method to give the user access to the provider objects using639 /// the get-childitem -name cmdlet.640 ///641 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>642 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those643 /// requirements by accessing the appropriate property from the base class. The exception to this644 /// is if <paramref name="returnAllContainers"/> is true, then any child name for a container should645 /// be returned even if it doesn't match the Filter, Include, or Exclude.646 ///647 /// By default overrides of this method should not write the names of objects that are generally hidden from648 /// the user unless the Force property is set to true. For instance, the FileSystem provider should649 /// not call WriteItemObject for hidden or system files unless the Force property is set to true.650 ///651 /// The provider implementation is responsible for preventing infinite recursion when there are652 /// circular links and the like. An appropriate terminating exception should be thrown if this653 /// situation occurs.654 ///655 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.656 /// </remarks>657 protected virtual void GetChildNames(658 string path,659 ReturnContainers returnContainers)660 {661 using (PSTransactionManager.GetEngineProtectionScope())662 {663 throw664 PSTraceSource.NewNotSupportedException(665 SessionStateStrings.CmdletProvider_NotSupported);666 }667 }668 669 /// <summary>670 /// Gets a new provider-specific path and filter (if any) that corresponds to the given671 /// path.672 /// </summary>673 /// <param name="path">674 /// The path to the item. Unlike most other provider APIs, this path is likely to675 /// contain PowerShell wildcards.676 /// </param>677 /// <param name="filter">678 /// The provider-specific filter currently applied.679 /// </param>680 /// <param name="updatedPath">681 /// The new path to the item.682 /// </param>683 /// <param name="updatedFilter">684 /// The new filter.685 /// </param>686 /// <returns>687 /// True if the path or filter were altered. False otherwise.688 /// </returns>689 /// <remarks>690 /// Providers override this method if they support a native filtering syntax that691 /// can offer performance improvements over wildcard matching done by the PowerShell692 /// engine.693 /// If the provider can handle a portion (or all) of the PowerShell wildcard with694 /// semantics equivalent to the PowerShell wildcard, it may adjust the path to exclude695 /// the PowerShell wildcard.696 /// If the provider can augment the PowerShell wildcard with an approximate filter (but697 /// not replace it entirely,) it may simply return a filter without modifying the path.698 /// In this situation, PowerShell's wildcarding will still be applied to a smaller result699 /// set, resulting in improved performance.700 ///701 /// The default implementation of this method leaves both Path and Filter unmodified.702 ///703 /// PowerShell wildcarding semantics are handled by the System.Management.Automation.Wildcardpattern704 /// class.705 /// </remarks>706 [SuppressMessage("Microsoft.Design", "CA1045:DoNotPassTypesByReference", MessageId = "2#")]707 [SuppressMessage("Microsoft.Design", "CA1045:DoNotPassTypesByReference", MessageId = "3#")]708 protected virtual bool ConvertPath(709 string path,710 string filter,711 ref string updatedPath,712 ref string updatedFilter)713 {714 using (PSTransactionManager.GetEngineProtectionScope())715 {716 return false;717 }718 }719 720 /// <summary>721 /// Gives the provider an opportunity to attach additional parameters to722 /// the get-childitem -name cmdlet.723 /// </summary>724 /// <param name="path">725 /// If the path was specified on the command line, this is the path726 /// to the item to get the dynamic parameters for.727 /// </param>728 /// <returns>729 /// Overrides of this method should return an object that has properties and fields decorated with730 /// parsing attributes similar to a cmdlet class or a731 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.732 ///733 /// The default implementation returns null. (no additional parameters)734 /// </returns>735 protected virtual object GetChildNamesDynamicParameters(string path)736 {737 using (PSTransactionManager.GetEngineProtectionScope())738 {739 return null;740 }741 }742 743 /// <summary>744 /// Renames the item at the specified path to the new name provided.745 /// </summary>746 /// <param name="path">747 /// The path to the item to rename.748 /// </param>749 /// <param name="newName">750 /// The name to which the item should be renamed. This name should always be751 /// relative to the parent container.752 /// </param>753 /// <returns>754 /// Nothing is returned, but the renamed items should be written to the WriteItemObject method.755 /// </returns>756 /// <remarks>757 /// Providers override this method to give the user the ability to rename provider objects using758 /// the rename-item cmdlet.759 ///760 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>761 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those762 /// requirements by accessing the appropriate property from the base class.763 ///764 /// By default overrides of this method should not allow renaming objects that are generally hidden from765 /// the user unless the Force property is set to true. For instance, the FileSystem provider should766 /// not allow renaming of a hidden or system file unless the Force property is set to true.767 ///768 /// This method is intended for the modification of the item's name only and not for Move operations.769 /// An error should be written to <see cref="CmdletProvider.WriteError"/> if the <paramref name="newName"/>770 /// parameter contains path separators or would cause the item to change its parent location.771 ///772 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.773 /// </remarks>774 protected virtual void RenameItem(775 string path,776 string newName)777 {778 using (PSTransactionManager.GetEngineProtectionScope())779 {780 throw781 PSTraceSource.NewNotSupportedException(782 SessionStateStrings.CmdletProvider_NotSupported);783 }784 }785 786 /// <summary>787 /// Gives the provider an opportunity to attach additional parameters to788 /// the rename-item cmdlet.789 /// </summary>790 /// <param name="path">791 /// If the path was specified on the command line, this is the path792 /// to the item to get the dynamic parameters for.793 /// </param>794 /// <param name="newName">795 /// The name to which the item should be renamed. This name should always be796 /// relative to the parent container.797 /// </param>798 /// <returns>799 /// Overrides of this method should return an object that has properties and fields decorated with800 /// parsing attributes similar to a cmdlet class or a801 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.802 ///803 /// The default implementation returns null. (no additional parameters)804 /// </returns>805 protected virtual object RenameItemDynamicParameters(string path, string newName)806 {807 using (PSTransactionManager.GetEngineProtectionScope())808 {809 return null;810 }811 }812 813 /// <summary>814 /// Creates a new item at the specified path.815 /// </summary>816 /// <param name="path">817 /// The path to the item to create.818 /// </param>819 /// <param name="itemTypeName">820 /// The provider defined type for the object to create.821 /// </param>822 /// <param name="newItemValue">823 /// This is a provider specific type that the provider can use to create a new824 /// instance of an item at the specified path.825 /// </param>826 /// <returns>827 /// Nothing is returned, but the renamed items should be written to the WriteItemObject method.828 /// </returns>829 /// <remarks>830 /// Providers override this method to give the user the ability to create new provider objects using831 /// the new-item cmdlet.832 ///833 /// The <paramref name="itemTypeName"/> parameter is a provider specific string that the user specifies to tell834 /// the provider what type of object to create. For instance, in the FileSystem provider the <paramref name="type"/>835 /// parameter can take a value of "file" or "directory". The comparison of this string should be836 /// case-insensitive and you should also allow for least ambiguous matches. So if the provider allows837 /// for the types "file" and "directory", only the first letter is required to disambiguate.838 /// If <paramref name="itemTypeName"/> refers to a type the provider cannot create, the provider should produce839 /// an <see cref="ArgumentException"/> with a message indicating the types the provider can create.840 ///841 /// The <paramref name="newItemValue"/> parameter can be any type of object that the provider can use842 /// to create the item. It is recommended that the provider accept at a minimum strings, and an instance843 /// of the type of object that would be returned from GetItem() for this path. <see cref="LanguagePrimitives.ConvertTo(object, System.Type)"/>844 /// can be used to convert some types to the desired type.845 ///846 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.847 /// </remarks>848 protected virtual void NewItem(849 string path,850 string itemTypeName,851 object newItemValue)852 {853 using (PSTransactionManager.GetEngineProtectionScope())854 {855 throw856 PSTraceSource.NewNotSupportedException(857 SessionStateStrings.CmdletProvider_NotSupported);858 }859 }860 861 /// <summary>862 /// Gives the provider an opportunity to attach additional parameters to863 /// the new-item cmdlet.864 /// </summary>865 /// <param name="path">866 /// If the path was specified on the command line, this is the path867 /// to the item to get the dynamic parameters for.868 /// </param>869 /// <param name="itemTypeName">870 /// The provider defined type of the item to create.871 /// </param>872 /// <param name="newItemValue">873 /// This is a provider specific type that the provider can use to create a new874 /// instance of an item at the specified path.875 /// </param>876 /// <returns>877 /// Overrides of this method should return an object that has properties and fields decorated with878 /// parsing attributes similar to a cmdlet class or a879 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.880 ///881 /// The default implementation returns null. (no additional parameters)882 /// </returns>883 protected virtual object NewItemDynamicParameters(884 string path,885 string itemTypeName,886 object newItemValue)887 {888 using (PSTransactionManager.GetEngineProtectionScope())889 {890 return null;891 }892 }893 894 /// <summary>895 /// Removes (deletes) the item at the specified path.896 /// </summary>897 /// <param name="path">898 /// The path to the item to remove.899 /// </param>900 /// <param name="recurse">901 /// True if all children in a subtree should be removed, false if only a single902 /// level of children should be removed. This parameter should only be true for903 /// NavigationCmdletProvider and its derived classes.904 /// </param>905 /// <returns>906 /// Nothing should be returned or written from this method.907 /// </returns>908 /// <remarks>909 /// Providers override this method to allow the user the ability to remove provider objects using910 /// the remove-item cmdlet.911 ///912 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>913 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those914 /// requirements by accessing the appropriate property from the base class.915 ///916 /// By default overrides of this method should not remove objects that are generally hidden from917 /// the user unless the Force property is set to true. For instance, the FileSystem provider should918 /// not remove a hidden or system file unless the Force property is set to true.919 ///920 /// The provider implementation is responsible for preventing infinite recursion when there are921 /// circular links and the like. An appropriate terminating exception should be thrown if this922 /// situation occurs.923 ///924 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.925 /// </remarks>926 protected virtual void RemoveItem(927 string path,928 bool recurse)929 {930 using (PSTransactionManager.GetEngineProtectionScope())931 {932 throw933 PSTraceSource.NewNotSupportedException(934 SessionStateStrings.CmdletProvider_NotSupported);935 }936 }937 938 /// <summary>939 /// Gives the provider an opportunity to attach additional parameters to940 /// the remove-item cmdlet.941 /// </summary>942 /// <param name="path">943 /// If the path was specified on the command line, this is the path944 /// to the item to get the dynamic parameters for.945 /// </param>946 /// <param name="recurse">947 /// True if all children in a subtree should be removed, false if only a single948 /// level of children should be removed. This parameter should only be true for949 /// NavigationCmdletProvider and its derived classes.950 /// </param>951 /// <returns>952 /// Overrides of this method should return an object that has properties and fields decorated with953 /// parsing attributes similar to a cmdlet class or a954 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.955 ///956 /// The default implementation returns null. (no additional parameters)957 /// </returns>958 protected virtual object RemoveItemDynamicParameters(959 string path,960 bool recurse)961 {962 using (PSTransactionManager.GetEngineProtectionScope())963 {964 return null;965 }966 }967 968 /// <summary>969 /// Determines if the item at the specified path has children.970 /// </summary>971 /// <param name="path">972 /// The path to the item to see if it has children.973 /// </param>974 /// <returns>975 /// True if the item has children, false otherwise.976 /// </returns>977 /// <returns>978 /// Nothing is returned, but all objects should be written to the WriteItemObject method.979 /// </returns>980 /// <remarks>981 /// Providers override this method to give the provider infrastructure the ability to determine982 /// if a particular provider object has children without having to retrieve all the child items.983 ///984 /// For implementers of <see cref="ContainerCmdletProvider"/> classes and those derived from it,985 /// if a null or empty path is passed,986 /// the provider should consider any items in the data store to be children987 /// and return true.988 ///989 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.990 /// </remarks>991 protected virtual bool HasChildItems(string path)992 {993 using (PSTransactionManager.GetEngineProtectionScope())994 {995 throw996 PSTraceSource.NewNotSupportedException(997 SessionStateStrings.CmdletProvider_NotSupported);998 }999 }1000 1001 /// <summary>1002 /// Copies an item at the specified path to an item at the <paramref name="copyPath"/>.1003 /// </summary>1004 /// <param name="path">1005 /// The path of the item to copy.1006 /// </param>1007 /// <param name="copyPath">1008 /// The path of the item to copy to.1009 /// </param>1010 /// <param name="recurse">1011 /// Tells the provider to recurse sub-containers when copying.1012 /// </param>1013 /// <returns>1014 /// Nothing is returned, but all the objects that were copied should be written to the WriteItemObject method.1015 /// </returns>1016 /// <remarks>1017 /// Providers override this method to give the user the ability to copy provider objects using1018 /// the copy-item cmdlet.1019 ///1020 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>1021 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path and items being copied1022 /// meets those requirements by accessing the appropriate property from the base class.1023 ///1024 /// By default overrides of this method should not copy objects over existing items unless the Force1025 /// property is set to true. For instance, the FileSystem provider should not copy c:\temp\foo.txt over1026 /// c:\bar.txt if c:\bar.txt already exists unless the Force parameter is true.1027 ///1028 /// If <paramref name="copyPath"/> exists and is a container then Force isn't required and <paramref name="path"/>1029 /// should be copied into the <paramref name="copyPath"/> container as a child.1030 ///1031 /// If <paramref name="recurse"/> is true, the provider implementation is responsible for1032 /// preventing infinite recursion when there are circular links and the like. An appropriate1033 /// terminating exception should be thrown if this situation occurs.1034 ///1035 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.1036 /// </remarks>1037 protected virtual void CopyItem(1038 string path,1039 string copyPath,1040 bool recurse)1041 {1042 using (PSTransactionManager.GetEngineProtectionScope())1043 {1044 throw1045 PSTraceSource.NewNotSupportedException(1046 SessionStateStrings.CmdletProvider_NotSupported);1047 }1048 }1049 1050 /// <summary>1051 /// Gives the provider an opportunity to attach additional parameters to1052 /// the copy-item cmdlet.1053 /// </summary>1054 /// <param name="path">1055 /// If the path was specified on the command line, this is the path1056 /// to the item to get the dynamic parameters for.1057 /// </param>1058 /// <param name="destination">1059 /// The path of the item to copy to.1060 /// </param>1061 /// <param name="recurse">1062 /// Tells the provider to recurse sub-containers when copying.1063 /// </param>1064 /// <returns>1065 /// Overrides of this method should return an object that has properties and fields decorated with1066 /// parsing attributes similar to a cmdlet class or a1067 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.1068 ///1069 /// The default implementation returns null. (no additional parameters)1070 /// </returns>1071 protected virtual object CopyItemDynamicParameters(1072 string path,1073 string destination,1074 bool recurse)1075 {1076 using (PSTransactionManager.GetEngineProtectionScope())1077 {1078 return null;1079 }1080 }1081 1082 #endregion Protected members1083 }1084 1085 #endregion ContainerCmdletProvider1086}1087