MegaBites-AI/Windows-powershell
0372
1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Management.Automation.Internal;5 6namespace System.Management.Automation.Provider7{8 #region ItemCmdletProvider9 10 /// <summary>11 /// The base class for Cmdlet providers that expose an item as a PowerShell path.12 /// </summary>13 /// <remarks>14 /// The ItemCmdletProvider class is a base class that a provider derives from to15 /// inherit a set of methods that allows the PowerShell engine16 /// to provide a core set of commands for getting and setting of data on one or17 /// more items. A provider should derive from this class if they want18 /// to take advantage of the item core commands that are19 /// already implemented by the engine. This allows users to have common20 /// commands and semantics across multiple providers.21 /// </remarks>22 public abstract class ItemCmdletProvider : DriveCmdletProvider23 {24 #region internal methods25 26 /// <summary>27 /// Internal wrapper for the GetItem protected method. It is called instead28 /// of the protected method that is overridden by derived classes so that the29 /// context of the command can be set.30 /// </summary>31 /// <param name="path">32 /// The path to the item to retrieve.33 /// </param>34 /// <param name="context">35 /// The context under which this method is being called.36 /// </param>37 /// <returns>38 /// Nothing is returned, but all objects should be written to the WriteObject method.39 /// </returns>40 internal void GetItem(string path, CmdletProviderContext context)41 {42 Context = context;43 44 // Call virtual method45 46 GetItem(path);47 }48 49 /// <summary>50 /// Gives the provider to attach additional parameters to51 /// the get-item cmdlet.52 /// </summary>53 /// <param name="path">54 /// If the path was specified on the command line, this is the path55 /// to the item to get the dynamic parameters for.56 /// </param>57 /// <param name="context">58 /// The context under which this method is being called.59 /// </param>60 /// <returns>61 /// Overrides of this method should return an object that has properties and fields decorated with62 /// parsing attributes similar to a cmdlet class or a63 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.64 ///65 /// The default implementation returns null. (no additional parameters)66 /// </returns>67 internal object GetItemDynamicParameters(string path, CmdletProviderContext context)68 {69 Context = context;70 return GetItemDynamicParameters(path);71 }72 73 /// <summary>74 /// Internal wrapper for the SetItem protected method. It is called instead75 /// of the protected method that is overridden by derived classes so that the76 /// context of the command can be set.77 /// </summary>78 /// <param name="path">79 /// The path to the item to set.80 /// </param>81 /// <param name="value">82 /// The value of the item specified by the path.83 /// </param>84 /// <param name="context">85 /// The context under which this method is being called.86 /// </param>87 /// <returns>88 /// The item that was set at the specified path.89 /// </returns>90 internal void SetItem(91 string path,92 object value,93 CmdletProviderContext context)94 {95 providerBaseTracer.WriteLine("ItemCmdletProvider.SetItem");96 97 Context = context;98 99 // Call virtual method100 101 SetItem(path, value);102 }103 104 /// <summary>105 /// Gives the provider to attach additional parameters to106 /// the set-item cmdlet.107 /// </summary>108 /// <param name="path">109 /// If the path was specified on the command line, this is the path110 /// to the item to get the dynamic parameters for.111 /// </param>112 /// <param name="value">113 /// The value of the item specified by the path.114 /// </param>115 /// <param name="context">116 /// The context under which this method is being called.117 /// </param>118 /// <returns>119 /// Overrides of this method should return an object that has properties and fields decorated with120 /// parsing attributes similar to a cmdlet class or a121 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.122 ///123 /// The default implementation returns null. (no additional parameters)124 /// </returns>125 internal object SetItemDynamicParameters(126 string path,127 object value,128 CmdletProviderContext context)129 {130 Context = context;131 return SetItemDynamicParameters(path, value);132 }133 134 /// <summary>135 /// Internal wrapper for the ClearItem protected method. It is called instead136 /// of the protected method that is overridden by derived classes so that the137 /// context of the command can be set.138 /// </summary>139 /// <param name="path">140 /// The path to the item to clear.141 /// </param>142 /// <param name="context">143 /// The context under which this method is being called.144 /// </param>145 internal void ClearItem(146 string path,147 CmdletProviderContext context)148 {149 providerBaseTracer.WriteLine("ItemCmdletProvider.ClearItem");150 151 Context = context;152 153 // Call virtual method154 155 ClearItem(path);156 }157 158 /// <summary>159 /// Gives the provider to attach additional parameters to160 /// the clear-item cmdlet.161 /// </summary>162 /// <param name="path">163 /// If the path was specified on the command line, this is the path164 /// to the item to get the dynamic parameters for.165 /// </param>166 /// <param name="context">167 /// The context under which this method is being called.168 /// </param>169 /// <returns>170 /// Overrides of this method should return an object that has properties and fields decorated with171 /// parsing attributes similar to a cmdlet class or a172 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.173 ///174 /// The default implementation returns null. (no additional parameters)175 /// </returns>176 internal object ClearItemDynamicParameters(177 string path,178 CmdletProviderContext context)179 {180 Context = context;181 return ClearItemDynamicParameters(path);182 }183 184 /// <summary>185 /// Internal wrapper for the InvokeDefaultAction protected method. It is called instead186 /// of the protected method that is overridden by derived classes so that the187 /// context of the command can be set.188 /// </summary>189 /// <param name="path">190 /// The path to the item to perform the default action on.191 /// </param>192 /// <param name="context">193 /// The context under which this method is being called.194 /// </param>195 internal void InvokeDefaultAction(196 string path,197 CmdletProviderContext context)198 {199 providerBaseTracer.WriteLine("ItemCmdletProvider.InvokeDefaultAction");200 201 Context = context;202 203 // Call virtual method204 205 InvokeDefaultAction(path);206 }207 208 /// <summary>209 /// Gives the provider to attach additional parameters to210 /// the invoke-item cmdlet.211 /// </summary>212 /// <param name="path">213 /// If the path was specified on the command line, this is the path214 /// to the item to get the dynamic parameters for.215 /// </param>216 /// <param name="context">217 /// The context under which this method is being called.218 /// </param>219 /// <returns>220 /// Overrides of this method should return an object that has properties and fields decorated with221 /// parsing attributes similar to a cmdlet class or a222 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.223 ///224 /// The default implementation returns null. (no additional parameters)225 /// </returns>226 internal object InvokeDefaultActionDynamicParameters(227 string path,228 CmdletProviderContext context)229 {230 Context = context;231 return InvokeDefaultActionDynamicParameters(path);232 }233 234 /// <summary>235 /// Internal wrapper for the Exists protected method. It is called instead236 /// of the protected method that is overridden by derived classes so that the237 /// context of the command can be set.238 /// </summary>239 /// <param name="path">240 /// The path to the item to see if it exists.241 /// </param>242 /// <param name="context">243 /// The context under which this method is being called.244 /// </param>245 /// <returns>246 /// True if the item exists, false otherwise.247 /// </returns>248 internal bool ItemExists(string path, CmdletProviderContext context)249 {250 Context = context;251 252 // Call virtual method253 254 bool itemExists = false;255 try256 {257 // Some providers don't expect non-valid path elements, and instead258 // throw an exception here.259 itemExists = ItemExists(path);260 }261 catch (Exception)262 {263 }264 265 return itemExists;266 }267 268 /// <summary>269 /// Gives the provider to attach additional parameters to270 /// the test-path cmdlet.271 /// </summary>272 /// <param name="path">273 /// If the path was specified on the command line, this is the path274 /// to the item to get the dynamic parameters for.275 /// </param>276 /// <param name="context">277 /// The context under which this method is being called.278 /// </param>279 /// <returns>280 /// Overrides of this method should return an object that has properties and fields decorated with281 /// parsing attributes similar to a cmdlet class or a282 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.283 ///284 /// The default implementation returns null. (no additional parameters)285 /// </returns>286 internal object ItemExistsDynamicParameters(287 string path,288 CmdletProviderContext context)289 {290 Context = context;291 return ItemExistsDynamicParameters(path);292 }293 294 /// <summary>295 /// Internal wrapper for the IsValidPath protected method. It is called instead296 /// of the protected method that is overridden by derived classes so that the297 /// context of the command can be set.298 /// </summary>299 /// <param name="path">300 /// The path to check for validity.301 /// </param>302 /// <param name="context">303 /// The context under which this method is being called.304 /// </param>305 /// <returns>306 /// True if the path is syntactically and semantically valid for the provider, or307 /// false otherwise.308 /// </returns>309 /// <remarks>310 /// This test should not verify the existence of the item at the path. It should311 /// only perform syntactic and semantic validation of the path. For instance, for312 /// the file system provider, that path should be canonicalized, syntactically verified,313 /// and ensure that the path does not refer to a device.314 /// </remarks>315 internal bool IsValidPath(string path, CmdletProviderContext context)316 {317 Context = context;318 319 // Call virtual method320 321 return IsValidPath(path);322 }323 324 /// <summary>325 /// Internal wrapper for the ExpandPath protected method. It is called instead326 /// of the protected method that is overridden by derived classes so that the327 /// context of the command can be set. Only called for providers that declare328 /// the ExpandWildcards capability.329 /// </summary>330 /// <param name="path">331 /// The path to expand. Expansion must be consistent with the wildcarding332 /// rules of PowerShell's WildcardPattern class.333 /// </param>334 /// <param name="context">335 /// The context under which this method is being called.336 /// </param>337 /// <returns>338 /// A list of provider paths that this path expands to. They must all exist.339 /// </returns>340 internal string[] ExpandPath(string path, CmdletProviderContext context)341 {342 Context = context;343 344 // Call virtual method345 return ExpandPath(path);346 }347 348 #endregion internal methods349 350 #region Protected methods351 352 /// <summary>353 /// Gets the item at the specified path.354 /// </summary>355 /// <param name="path">356 /// The path to the item to retrieve.357 /// </param>358 /// <returns>359 /// Nothing is returned, but all objects should be written to the WriteItemObject method.360 /// </returns>361 /// <remarks>362 /// Providers override this method to give the user access to the provider objects using363 /// the get-item and get-childitem cmdlets.364 ///365 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>366 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those367 /// requirements by accessing the appropriate property from the base class.368 ///369 /// By default overrides of this method should not write objects that are generally hidden from370 /// the user unless the Force property is set to true. For instance, the FileSystem provider should371 /// not call WriteItemObject for hidden or system files unless the Force property is set to true.372 ///373 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.374 /// </remarks>375 protected virtual void GetItem(string path)376 {377 using (PSTransactionManager.GetEngineProtectionScope())378 {379 throw380 PSTraceSource.NewNotSupportedException(381 SessionStateStrings.CmdletProvider_NotSupported);382 }383 }384 385 /// <summary>386 /// Gives the provider an opportunity to attach additional parameters to387 /// the get-item cmdlet.388 /// </summary>389 /// <param name="path">390 /// If the path was specified on the command line, this is the path391 /// to the item to get the dynamic parameters for.392 /// </param>393 /// <returns>394 /// Overrides of this method should return an object that has properties and fields decorated with395 /// parsing attributes similar to a cmdlet class or a396 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.397 ///398 /// The default implementation returns null. (no additional parameters)399 /// </returns>400 protected virtual object GetItemDynamicParameters(string path)401 {402 using (PSTransactionManager.GetEngineProtectionScope())403 {404 return null;405 }406 }407 408 /// <summary>409 /// Sets the item specified by the path.410 /// </summary>411 /// <param name="path">412 /// The path to the item to set.413 /// </param>414 /// <param name="value">415 /// The value of the item specified by the path.416 /// </param>417 /// <returns>418 /// Nothing. The item that was set should be passed to the WriteItemObject method.419 /// </returns>420 /// <remarks>421 /// Providers override this method to give the user the ability to modify provider objects using422 /// the set-item cmdlet.423 ///424 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>425 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those426 /// requirements by accessing the appropriate property from the base class.427 ///428 /// By default overrides of this method should not set or write objects that are generally hidden from429 /// the user unless the Force property is set to true. An error should be sent to the WriteError method if430 /// the path represents an item that is hidden from the user and Force is set to false.431 ///432 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.433 /// </remarks>434 protected virtual void SetItem(435 string path,436 object value)437 {438 using (PSTransactionManager.GetEngineProtectionScope())439 {440 throw441 PSTraceSource.NewNotSupportedException(442 SessionStateStrings.CmdletProvider_NotSupported);443 }444 }445 446 /// <summary>447 /// Gives the provider an opportunity to attach additional parameters to448 /// the set-item cmdlet.449 /// </summary>450 /// <param name="path">451 /// If the path was specified on the command line, this is the path452 /// to the item to get the dynamic parameters for.453 /// </param>454 /// <param name="value">455 /// The value of the item specified by the path.456 /// </param>457 /// <returns>458 /// Overrides of this method should return an object that has properties and fields decorated with459 /// parsing attributes similar to a cmdlet class or a460 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.461 ///462 /// The default implementation returns null. (no additional parameters)463 /// </returns>464 protected virtual object SetItemDynamicParameters(string path, object value)465 {466 using (PSTransactionManager.GetEngineProtectionScope())467 {468 return null;469 }470 }471 472 /// <summary>473 /// Clears the item specified by the path.474 /// </summary>475 /// <param name="path">476 /// The path to the item to clear.477 /// </param>478 /// <returns>479 /// Nothing. The item that was cleared should be passed to the WriteItemObject method.480 /// </returns>481 /// <remarks>482 /// Providers override this method to give the user the ability to clear provider objects using483 /// the clear-item cmdlet.484 ///485 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>486 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those487 /// requirements by accessing the appropriate property from the base class.488 ///489 /// By default overrides of this method should not clear or write objects that are generally hidden from490 /// the user unless the Force property is set to true. An error should be sent to the WriteError method if491 /// the path represents an item that is hidden from the user and Force is set to false.492 ///493 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.494 /// </remarks>495 protected virtual void ClearItem(496 string path)497 {498 using (PSTransactionManager.GetEngineProtectionScope())499 {500 throw501 PSTraceSource.NewNotSupportedException(502 SessionStateStrings.CmdletProvider_NotSupported);503 }504 }505 506 /// <summary>507 /// Gives the provider an opportunity to attach additional parameters to508 /// the clear-item cmdlet.509 /// </summary>510 /// <param name="path">511 /// If the path was specified on the command line, this is the path512 /// to the item to get the dynamic parameters for.513 /// </param>514 /// <returns>515 /// Overrides of this method should return an object that has properties and fields decorated with516 /// parsing attributes similar to a cmdlet class or a517 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.518 ///519 /// The default implementation returns null. (no additional parameters)520 /// </returns>521 protected virtual object ClearItemDynamicParameters(string path)522 {523 using (PSTransactionManager.GetEngineProtectionScope())524 {525 return null;526 }527 }528 529 /// <summary>530 /// Invokes the default action on the specified item.531 /// </summary>532 /// <param name="path">533 /// The path to the item to perform the default action on.534 /// </param>535 /// <returns>536 /// Nothing. The item that was set should be passed to the WriteItemObject method.537 /// </returns>538 /// <remarks>539 /// The default implementation does nothing.540 ///541 /// Providers override this method to give the user the ability to invoke provider objects using542 /// the invoke-item cmdlet. Think of the invocation as a double click in the Windows Shell. This543 /// method provides a default action based on the path that was passed.544 ///545 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>546 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those547 /// requirements by accessing the appropriate property from the base class.548 ///549 /// By default overrides of this method should not invoke objects that are generally hidden from550 /// the user unless the Force property is set to true. An error should be sent to the WriteError method if551 /// the path represents an item that is hidden from the user and Force is set to false.552 /// </remarks>553 protected virtual void InvokeDefaultAction(554 string path)555 {556 using (PSTransactionManager.GetEngineProtectionScope())557 {558 throw559 PSTraceSource.NewNotSupportedException(560 SessionStateStrings.CmdletProvider_NotSupported);561 }562 }563 564 /// <summary>565 /// Gives the provider an opportunity to attach additional parameters to566 /// the invoke-item cmdlet.567 /// </summary>568 /// <param name="path">569 /// If the path was specified on the command line, this is the path570 /// to the item to get the dynamic parameters for.571 /// </param>572 /// <returns>573 /// Overrides of this method should return an object that has properties and fields decorated with574 /// parsing attributes similar to a cmdlet class or a575 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.576 ///577 /// The default implementation returns null. (no additional parameters)578 /// </returns>579 protected virtual object InvokeDefaultActionDynamicParameters(string path)580 {581 using (PSTransactionManager.GetEngineProtectionScope())582 {583 return null;584 }585 }586 587 /// <summary>588 /// Determines if an item exists at the specified path.589 /// </summary>590 /// <param name="path">591 /// The path to the item to see if it exists.592 /// </param>593 /// <returns>594 /// True if the item exists, false otherwise.595 /// </returns>596 /// <returns>597 /// Nothing. The item that was set should be passed to the WriteItemObject method.598 /// </returns>599 /// <remarks>600 /// Providers override this method to give the user the ability to check for the existence of provider objects using601 /// the set-item cmdlet.602 ///603 /// Providers that declare <see cref="System.Management.Automation.Provider.ProviderCapabilities"/>604 /// of ExpandWildcards, Filter, Include, or Exclude should ensure that the path passed meets those605 /// requirements by accessing the appropriate property from the base class.606 ///607 /// The implementation of this method should take into account any form of access to the object that may608 /// make it visible to the user. For instance, if a user has write access to a file in the file system609 /// provider bug not read access, the file still exists and the method should return true. Sometimes this610 /// may require checking the parent to see if the child can be enumerated.611 ///612 /// The default implementation of this method throws an <see cref="System.Management.Automation.PSNotSupportedException"/>.613 /// </remarks>614 protected virtual bool ItemExists(string path)615 {616 using (PSTransactionManager.GetEngineProtectionScope())617 {618 throw619 PSTraceSource.NewNotSupportedException(620 SessionStateStrings.CmdletProvider_NotSupported);621 }622 }623 624 /// <summary>625 /// Gives the provider an opportunity to attach additional parameters to626 /// the test-path cmdlet.627 /// </summary>628 /// <param name="path">629 /// If the path was specified on the command line, this is the path630 /// to the item to get the dynamic parameters for.631 /// </param>632 /// <returns>633 /// Overrides of this method should return an object that has properties and fields decorated with634 /// parsing attributes similar to a cmdlet class or a635 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.636 ///637 /// The default implementation returns null. (no additional parameters)638 /// </returns>639 protected virtual object ItemExistsDynamicParameters(string path)640 {641 using (PSTransactionManager.GetEngineProtectionScope())642 {643 return null;644 }645 }646 647 /// <summary>648 /// Providers must override this method to verify the syntax and semantics649 /// of their paths.650 /// </summary>651 /// <param name="path">652 /// The path to check for validity.653 /// </param>654 /// <returns>655 /// True if the path is syntactically and semantically valid for the provider, or656 /// false otherwise.657 /// </returns>658 /// <remarks>659 /// This test should not verify the existence of the item at the path. It should660 /// only perform syntactic and semantic validation of the path. For instance, for661 /// the file system provider, that path should be canonicalized, syntactically verified,662 /// and ensure that the path does not refer to a device.663 /// </remarks>664 protected abstract bool IsValidPath(string path);665 666 /// <summary>667 /// Expand a provider path that contains wildcards to a list of provider668 /// paths that the path represents.Only called for providers that declare669 /// the ExpandWildcards capability.670 /// </summary>671 /// <param name="path">672 /// The path to expand. Expansion must be consistent with the wildcarding673 /// rules of PowerShell's WildcardPattern class.674 /// </param>675 /// <returns>676 /// A list of provider paths that this path expands to. They must all exist.677 /// </returns>678 protected virtual string[] ExpandPath(string path)679 {680 using (PSTransactionManager.GetEngineProtectionScope())681 {682 return new string[] { path };683 }684 }685 686 #endregion Protected methods687 }688 689 #endregion ItemCmdletProvider690}691