MegaBites-AI/Windows-powershell
0372
1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4#pragma warning disable 1634, 16915#pragma warning disable 565066 7using System.Collections.ObjectModel;8using System.IO;9using System.Management.Automation.Runspaces;10using System.Management.Automation.Internal;11using System.Management.Automation.Host;12using System.Resources;13using System.Diagnostics.CodeAnalysis; // for fxcop14using System.Security.AccessControl;15 16namespace System.Management.Automation.Provider17{18 19 /// <summary>20 /// This interface needs to be implemented by providers that want users to see21 /// provider-specific help.22 /// </summary>23#nullable enable24 public interface ICmdletProviderSupportsHelp25 {26 /// <summary>27 /// Called by the help system to get provider-specific help from the provider.28 /// </summary>29 /// <param name="helpItemName">30 /// Name of command that the help is requested for.31 /// </param>32 /// <param name="path">33 /// Full path to the current location of the user or the full path to34 /// the location of the property that the user needs help about.35 /// </param>36 /// <returns>37 /// The MAML help XML that should be presented to the user.38 /// </returns>39 [SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Maml", Justification = "Maml is an acronym.")]40 string GetHelpMaml(string helpItemName, string path);41 }42#nullable restore43 #region CmdletProvider44 45 /// <summary>46 /// The base class for Cmdlet provider.47 /// </summary>48 /// <remarks>49 /// Although it is possible to derive from this base class to implement a Cmdlet Provider, in most50 /// cases one should derive from <see cref="System.Management.Automation.Provider.ItemCmdletProvider"/>,51 /// <see cref="System.Management.Automation.Provider.ContainerCmdletProvider"/>, or52 /// <see cref ="System.Management.Automation.Provider.NavigationCmdletProvider"/>53 /// </remarks>54 public abstract partial class CmdletProvider : IResourceSupplier55 {56 #region private data57 58 /// <summary>59 /// The context under which the provider is running. This will change between each60 /// invocation of a method in this class or derived classes.61 /// </summary>62 private CmdletProviderContext _contextBase = null;63 64 /// <summary>65 /// The information that the Monad engine stores on behalf of the provider.66 /// </summary>67 private ProviderInfo _providerInformation = null;68 69 #endregion private data70 71 #region internal members72 73 #region Trace object74 75 /// <summary>76 /// An instance of the PSTraceSource class used for trace output77 /// using "CmdletProviderClasses" as the category.78 /// </summary>79 [TraceSource(80 "CmdletProviderClasses",81 "The namespace provider base classes tracer")]82 internal static readonly PSTraceSource providerBaseTracer = PSTraceSource.GetTracer(83 "CmdletProviderClasses",84 "The namespace provider base classes tracer");85 86 #endregion Trace object87 88 /// <summary>89 /// Sets the provider information that is stored in the Monad engine into the90 /// provider base class.91 /// </summary>92 /// <param name="providerInfoToSet">93 /// The provider information that is stored by the Monad engine.94 /// </param>95 /// <exception cref="ArgumentNullException">96 /// If <paramref name="providerInformation"/> is null.97 /// </exception>98 internal void SetProviderInformation(ProviderInfo providerInfoToSet)99 {100 if (providerInfoToSet == null)101 {102 throw PSTraceSource.NewArgumentNullException(nameof(providerInfoToSet));103 }104 105 _providerInformation = providerInfoToSet;106 }107 108 /// <summary>109 /// Checks whether the filter of the provider is set.110 /// Can be overridden by derived class when additional filters are defined.111 /// </summary>112 /// <returns>113 /// Whether the filter of the provider is set.114 /// </returns>115 internal virtual bool IsFilterSet()116 {117 bool filterSet = !string.IsNullOrEmpty(Filter);118 return filterSet;119 }120 121 #region CmdletProvider method wrappers122 123 /// <summary>124 /// Gets or sets the context for the running command.125 /// </summary>126 /// <exception cref="NotSupportedException">127 /// On set, if the context contains credentials and the provider128 /// doesn't support credentials, or if the context contains a filter129 /// parameter and the provider does not support filters.130 /// </exception>131 internal CmdletProviderContext Context132 {133 get134 {135 return _contextBase;136 }137 138 set139 {140 if (value == null)141 {142 throw PSTraceSource.NewArgumentNullException("value");143 }144 145 // Check that the provider supports the use of credentials146 if (value.Credential != null &&147 value.Credential != PSCredential.Empty &&148 !CmdletProviderManagementIntrinsics.CheckProviderCapabilities(ProviderCapabilities.Credentials, _providerInformation))149 {150 throw PSTraceSource.NewNotSupportedException(151 SessionStateStrings.Credentials_NotSupported);152 }153 154 // Supplying Credentials for the FileSystemProvider is supported only for New-PSDrive Command.155 if (_providerInformation != null && !string.IsNullOrEmpty(_providerInformation.Name) && _providerInformation.Name.Equals("FileSystem") &&156 value.Credential != null &&157 value.Credential != PSCredential.Empty &&158 !value.ExecutionContext.CurrentCommandProcessor.Command.GetType().Name.Equals("NewPSDriveCommand"))159 {160 throw PSTraceSource.NewNotSupportedException(161 SessionStateStrings.FileSystemProviderCredentials_NotSupported);162 }163 164 // Check that the provider supports the use of filters165 if ((!string.IsNullOrEmpty(value.Filter)) &&166 (!CmdletProviderManagementIntrinsics.CheckProviderCapabilities(ProviderCapabilities.Filter, _providerInformation)))167 {168 throw PSTraceSource.NewNotSupportedException(169 SessionStateStrings.Filter_NotSupported);170 }171 172 // Check that the provider supports the use of transactions if the command173 // requested it174 if ((value.UseTransaction) &&175 (!CmdletProviderManagementIntrinsics.CheckProviderCapabilities(ProviderCapabilities.Transactions, _providerInformation)))176 {177 throw PSTraceSource.NewNotSupportedException(178 SessionStateStrings.Transactions_NotSupported);179 }180 181 _contextBase = value;182 _contextBase.ProviderInstance = this;183 }184 }185 186 /// <summary>187 /// Called when the provider is first initialized. It sets the context188 /// of the call and then calls the derived providers Start method.189 /// </summary>190 /// <param name="providerInfo">191 /// The information about the provider.192 /// </param>193 /// <param name="cmdletProviderContext">194 /// The context under which this method is being called.195 /// </param>196 internal ProviderInfo Start(ProviderInfo providerInfo, CmdletProviderContext cmdletProviderContext)197 {198 Context = cmdletProviderContext;199 return Start(providerInfo);200 }201 202 /// <summary>203 /// Gets an object that defines the additional parameters for the Start implementation204 /// for a provider.205 /// </summary>206 /// <param name="cmdletProviderContext">207 /// The context under which this method is being called.208 /// </param>209 /// <returns>210 /// An object that has properties and fields decorated with211 /// parsing attributes similar to a cmdlet class.212 /// </returns>213 internal object StartDynamicParameters(CmdletProviderContext cmdletProviderContext)214 {215 Context = cmdletProviderContext;216 217 return StartDynamicParameters();218 }219 220 /// <summary>221 /// Called when the provider is being removed. It sets the context222 /// of the call and then calls the derived providers Stop method.223 /// </summary>224 /// <param name="cmdletProviderContext">225 /// The context under which this method is being called.226 /// </param>227 internal void Stop(CmdletProviderContext cmdletProviderContext)228 {229 Context = cmdletProviderContext;230 Stop();231 }232 233 /// <Content contentref="System.Management.Automation.Cmdlet.StopProcessing" />234 protected internal virtual void StopProcessing()235 {236 }237 238 #endregion CmdletProvider method wrappers239 240 #region IPropertyCmdletProvider method wrappers241 242 /// <summary>243 /// Internal wrapper for the GetProperty protected method. This method will244 /// only be called if the provider implements the IPropertyCmdletProvider interface.245 /// </summary>246 /// <param name="path">247 /// The path to the item to retrieve properties from.248 /// </param>249 /// <param name="providerSpecificPickList">250 /// A list of properties that should be retrieved. If this parameter is null251 /// or empty, all properties should be retrieved.252 /// </param>253 /// <param name="cmdletProviderContext">254 /// The context under which this method is being called.255 /// </param>256 internal void GetProperty(257 string path,258 Collection<string> providerSpecificPickList,259 CmdletProviderContext cmdletProviderContext)260 {261 Context = cmdletProviderContext;262 263 if (this is not IPropertyCmdletProvider propertyProvider)264 {265 throw266 PSTraceSource.NewNotSupportedException(267 SessionStateStrings.IPropertyCmdletProvider_NotSupported);268 }269 270 // Call interface method271 272 propertyProvider.GetProperty(path, providerSpecificPickList);273 }274 275 /// <summary>276 /// Gives the provider a chance to attach additional parameters to277 /// the get-itemproperty cmdlet.278 /// </summary>279 /// <param name="path">280 /// If the path was specified on the command line, this is the path281 /// to the item to get the dynamic parameters for.282 /// </param>283 /// <param name="providerSpecificPickList">284 /// A list of properties that should be retrieved. If this parameter is null285 /// or empty, all properties should be retrieved.286 /// </param>287 /// <param name="cmdletProviderContext">288 /// The context under which this method is being called.289 /// </param>290 /// <returns>291 /// An object that has properties and fields decorated with292 /// parsing attributes similar to a cmdlet class.293 /// </returns>294 internal object GetPropertyDynamicParameters(295 string path,296 Collection<string> providerSpecificPickList,297 CmdletProviderContext cmdletProviderContext)298 {299 Context = cmdletProviderContext;300 301 if (this is not IPropertyCmdletProvider propertyProvider)302 {303 return null;304 }305 306 return propertyProvider.GetPropertyDynamicParameters(path, providerSpecificPickList);307 }308 309 /// <summary>310 /// Internal wrapper for the SetProperty protected method. This method will311 /// only be called if the provider implements the IPropertyCmdletProvider interface.312 /// </summary>313 /// <param name="path">314 /// The path to the item to set the properties on.315 /// </param>316 /// <param name="propertyValue">317 /// A PSObject which contains a collection of the name, type, value318 /// of the properties to be set.319 /// </param>320 /// <param name="cmdletProviderContext">321 /// The context under which this method is being called.322 /// </param>323 internal void SetProperty(324 string path,325 PSObject propertyValue,326 CmdletProviderContext cmdletProviderContext)327 {328 Context = cmdletProviderContext;329 330 if (this is not IPropertyCmdletProvider propertyProvider)331 {332 throw333 PSTraceSource.NewNotSupportedException(334 SessionStateStrings.IPropertyCmdletProvider_NotSupported);335 }336 337 // Call interface method338 339 propertyProvider.SetProperty(path, propertyValue);340 }341 342 /// <summary>343 /// Gives the provider a chance to attach additional parameters to344 /// the set-itemproperty cmdlet.345 /// </summary>346 /// <param name="path">347 /// If the path was specified on the command line, this is the path348 /// to the item to get the dynamic parameters for.349 /// </param>350 /// <param name="propertyValue">351 /// A PSObject which contains a collection of the name, type, value352 /// of the properties to be set.353 /// </param>354 /// <param name="cmdletProviderContext">355 /// The context under which this method is being called.356 /// </param>357 /// <returns>358 /// An object that has properties and fields decorated with359 /// parsing attributes similar to a cmdlet class.360 /// </returns>361 internal object SetPropertyDynamicParameters(362 string path,363 PSObject propertyValue,364 CmdletProviderContext cmdletProviderContext)365 {366 Context = cmdletProviderContext;367 368 if (this is not IPropertyCmdletProvider propertyProvider)369 {370 return null;371 }372 373 return propertyProvider.SetPropertyDynamicParameters(path, propertyValue);374 }375 376 /// <summary>377 /// Internal wrapper for the ClearProperty protected method. This method will378 /// only be called if the provider implements the IPropertyCmdletProvider interface.379 /// </summary>380 /// <param name="path">381 /// The path to the item from which the property should be cleared.382 /// </param>383 /// <param name="propertyName">384 /// The name of the property that should be cleared.385 /// </param>386 /// <param name="cmdletProviderContext">387 /// The context under which this method is being called.388 /// </param>389 /// <remarks>390 /// Implement this method when you are providing access to a data store391 /// that allows dynamic clearing of properties.392 /// </remarks>393 internal void ClearProperty(394 string path,395 Collection<string> propertyName,396 CmdletProviderContext cmdletProviderContext)397 {398 Context = cmdletProviderContext;399 400 if (this is not IPropertyCmdletProvider propertyProvider)401 {402 throw403 PSTraceSource.NewNotSupportedException(404 SessionStateStrings.IPropertyCmdletProvider_NotSupported);405 }406 407 // Call interface method408 409 propertyProvider.ClearProperty(path, propertyName);410 }411 412 /// <summary>413 /// Gives the provider a chance to attach additional parameters to414 /// the clear-itemproperty cmdlet.415 /// </summary>416 /// <param name="path">417 /// If the path was specified on the command line, this is the path418 /// to the item to get the dynamic parameters for.419 /// </param>420 /// <param name="providerSpecificPickList">421 /// A list of properties that should be cleared. If this parameter is null422 /// or empty, all properties should be cleared.423 /// </param>424 /// <param name="cmdletProviderContext">425 /// The context under which this method is being called.426 /// </param>427 /// <returns>428 /// An object that has properties and fields decorated with429 /// parsing attributes similar to a cmdlet class.430 /// </returns>431 internal object ClearPropertyDynamicParameters(432 string path,433 Collection<string> providerSpecificPickList,434 CmdletProviderContext cmdletProviderContext)435 {436 Context = cmdletProviderContext;437 438 if (this is not IPropertyCmdletProvider propertyProvider)439 {440 return null;441 }442 443 return propertyProvider.ClearPropertyDynamicParameters(path, providerSpecificPickList);444 }445 446 #endregion IPropertyCmdletProvider447 448 #region IDynamicPropertyCmdletProvider449 450 /// <summary>451 /// Internal wrapper for the NewProperty protected method. This method will452 /// only be called if the provider implements the IDynamicPropertyCmdletProvider interface.453 /// </summary>454 /// <param name="path">455 /// The path to the item on which the new property should be created.456 /// </param>457 /// <param name="propertyName">458 /// The name of the property that should be created.459 /// </param>460 /// <param name="propertyTypeName">461 /// The type of the property that should be created.462 /// </param>463 /// <param name="value">464 /// The new value of the property that should be created.465 /// </param>466 /// <param name="cmdletProviderContext">467 /// The context under which this method is being called.468 /// </param>469 /// <remarks>470 /// Implement this method when you are providing access to a data store471 /// that allows dynamic creation of properties.472 /// </remarks>473 internal void NewProperty(474 string path,475 string propertyName,476 string propertyTypeName,477 object value,478 CmdletProviderContext cmdletProviderContext)479 {480 Context = cmdletProviderContext;481 482 if (this is not IDynamicPropertyCmdletProvider propertyProvider)483 {484 throw485 PSTraceSource.NewNotSupportedException(486 SessionStateStrings.IDynamicPropertyCmdletProvider_NotSupported);487 }488 489 // Call interface method490 491 propertyProvider.NewProperty(path, propertyName, propertyTypeName, value);492 }493 494 /// <summary>495 /// Gives the provider a chance to attach additional parameters to496 /// the new-itemproperty cmdlet.497 /// </summary>498 /// <param name="path">499 /// If the path was specified on the command line, this is the path500 /// to the item to get the dynamic parameters for.501 /// </param>502 /// <param name="propertyName">503 /// The name of the property that should be created.504 /// </param>505 /// <param name="propertyTypeName">506 /// The type of the property that should be created.507 /// </param>508 /// <param name="value">509 /// The new value of the property that should be created.510 /// </param>511 /// <param name="cmdletProviderContext">512 /// The context under which this method is being called.513 /// </param>514 /// <returns>515 /// An object that has properties and fields decorated with516 /// parsing attributes similar to a cmdlet class.517 /// </returns>518 internal object NewPropertyDynamicParameters(519 string path,520 string propertyName,521 string propertyTypeName,522 object value,523 CmdletProviderContext cmdletProviderContext)524 {525 Context = cmdletProviderContext;526 527 if (this is not IDynamicPropertyCmdletProvider propertyProvider)528 {529 return null;530 }531 532 return propertyProvider.NewPropertyDynamicParameters(path, propertyName, propertyTypeName, value);533 }534 535 /// <summary>536 /// Internal wrapper for the RemoveProperty protected method. This method will537 /// only be called if the provider implements the IDynamicPropertyCmdletProvider interface.538 /// </summary>539 /// <param name="path">540 /// The path to the item on which the property should be removed.541 /// </param>542 /// <param name="propertyName">543 /// The name of the property to be removed544 /// </param>545 /// <param name="cmdletProviderContext">546 /// The context under which this method is being called.547 /// </param>548 /// <remarks>549 /// Implement this method when you are providing access to a data store550 /// that allows dynamic removal of properties.551 /// </remarks>552 internal void RemoveProperty(553 string path,554 string propertyName,555 CmdletProviderContext cmdletProviderContext)556 {557 Context = cmdletProviderContext;558 559 if (this is not IDynamicPropertyCmdletProvider propertyProvider)560 {561 throw562 PSTraceSource.NewNotSupportedException(563 SessionStateStrings.IDynamicPropertyCmdletProvider_NotSupported);564 }565 566 // Call interface method567 568 propertyProvider.RemoveProperty(path, propertyName);569 }570 571 /// <summary>572 /// Gives the provider a chance to attach additional parameters to573 /// the remove-itemproperty cmdlet.574 /// </summary>575 /// <param name="path">576 /// If the path was specified on the command line, this is the path577 /// to the item to get the dynamic parameters for.578 /// </param>579 /// <param name="propertyName">580 /// The name of the property that should be removed.581 /// </param>582 /// <param name="cmdletProviderContext">583 /// The context under which this method is being called.584 /// </param>585 /// <returns>586 /// An object that has properties and fields decorated with587 /// parsing attributes similar to a cmdlet class.588 /// </returns>589 internal object RemovePropertyDynamicParameters(590 string path,591 string propertyName,592 CmdletProviderContext cmdletProviderContext)593 {594 Context = cmdletProviderContext;595 596 if (this is not IDynamicPropertyCmdletProvider propertyProvider)597 {598 return null;599 }600 601 return propertyProvider.RemovePropertyDynamicParameters(path, propertyName);602 }603 604 /// <summary>605 /// Internal wrapper for the RenameProperty protected method. This method will606 /// only be called if the provider implements the IDynamicPropertyCmdletProvider interface.607 /// </summary>608 /// <param name="path">609 /// The path to the item on which the property should be renamed.610 /// </param>611 /// <param name="propertyName">612 /// The name of the property that should be renamed.613 /// </param>614 /// <param name="newPropertyName">615 /// The new name for the property.616 /// </param>617 /// <param name="cmdletProviderContext">618 /// The context under which this method is being called.619 /// </param>620 /// <remarks>621 /// Implement this method when you are providing access to a data store622 /// that allows dynamic renaming of properties.623 /// </remarks>624 internal void RenameProperty(625 string path,626 string propertyName,627 string newPropertyName,628 CmdletProviderContext cmdletProviderContext)629 {630 Context = cmdletProviderContext;631 632 if (this is not IDynamicPropertyCmdletProvider propertyProvider)633 {634 throw635 PSTraceSource.NewNotSupportedException(636 SessionStateStrings.IDynamicPropertyCmdletProvider_NotSupported);637 }638 639 // Call interface method640 641 propertyProvider.RenameProperty(path, propertyName, newPropertyName);642 }643 644 /// <summary>645 /// Gives the provider a chance to attach additional parameters to646 /// the rename-itemproperty cmdlet.647 /// </summary>648 /// <param name="path">649 /// If the path was specified on the command line, this is the path650 /// to the item to get the dynamic parameters for.651 /// </param>652 /// <param name="sourceProperty">653 /// The name of the property that should be renamed.654 /// </param>655 /// <param name="destinationProperty">656 /// The name of the property to rename it to.657 /// </param>658 /// <param name="cmdletProviderContext">659 /// The context under which this method is being called.660 /// </param>661 /// <returns>662 /// An object that has properties and fields decorated with663 /// parsing attributes similar to a cmdlet class.664 /// </returns>665 internal object RenamePropertyDynamicParameters(666 string path,667 string sourceProperty,668 string destinationProperty,669 CmdletProviderContext cmdletProviderContext)670 {671 Context = cmdletProviderContext;672 673 if (this is not IDynamicPropertyCmdletProvider propertyProvider)674 {675 return null;676 }677 678 return propertyProvider.RenamePropertyDynamicParameters(path, sourceProperty, destinationProperty);679 }680 681 /// <summary>682 /// Internal wrapper for the CopyProperty protected method. This method will683 /// only be called if the provider implements the IDynamicPropertyCmdletProvider interface.684 /// </summary>685 /// <param name="sourcePath">686 /// The path to the item from which the property should be copied.687 /// </param>688 /// <param name="sourceProperty">689 /// The name of the property that should be copied.690 /// </param>691 /// <param name="destinationPath">692 /// The path to the item to which the property should be copied.693 /// </param>694 /// <param name="destinationProperty">695 /// The name of the property that should be copied to.696 /// </param>697 /// <param name="cmdletProviderContext">698 /// The context under which this method is being called.699 /// </param>700 /// <remarks>701 /// Implement this method when you are providing access to a data store702 /// that allows dynamic copying of properties.703 /// </remarks>704 internal void CopyProperty(705 string sourcePath,706 string sourceProperty,707 string destinationPath,708 string destinationProperty,709 CmdletProviderContext cmdletProviderContext)710 {711 Context = cmdletProviderContext;712 713 if (this is not IDynamicPropertyCmdletProvider propertyProvider)714 {715 throw716 PSTraceSource.NewNotSupportedException(717 SessionStateStrings.IDynamicPropertyCmdletProvider_NotSupported);718 }719 720 // Call interface method721 722 propertyProvider.CopyProperty(sourcePath, sourceProperty, destinationPath, destinationProperty);723 }724 725 /// <summary>726 /// Gives the provider a chance to attach additional parameters to727 /// the copy-itemproperty cmdlet.728 /// </summary>729 /// <param name="path">730 /// If the path was specified on the command line, this is the path731 /// to the item to get the dynamic parameters for.732 /// </param>733 /// <param name="sourceProperty">734 /// The name of the property that should be copied.735 /// </param>736 /// <param name="destinationPath">737 /// The path to the item to which the property should be copied.738 /// </param>739 /// <param name="destinationProperty">740 /// The name of the property that should be copied to.741 /// </param>742 /// <param name="cmdletProviderContext">743 /// The context under which this method is being called.744 /// </param>745 /// <returns>746 /// An object that has properties and fields decorated with747 /// parsing attributes similar to a cmdlet class.748 /// </returns>749 internal object CopyPropertyDynamicParameters(750 string path,751 string sourceProperty,752 string destinationPath,753 string destinationProperty,754 CmdletProviderContext cmdletProviderContext)755 {756 Context = cmdletProviderContext;757 758 if (this is not IDynamicPropertyCmdletProvider propertyProvider)759 {760 return null;761 }762 763 return propertyProvider.CopyPropertyDynamicParameters(path, sourceProperty, destinationPath, destinationProperty);764 }765 766 /// <summary>767 /// Internal wrapper for the MoveProperty protected method. This method will768 /// only be called if the provider implements the IDynamicPropertyCmdletProvider interface.769 /// </summary>770 /// <param name="sourcePath">771 /// The path to the item from which the property should be moved.772 /// </param>773 /// <param name="sourceProperty">774 /// The name of the property that should be moved.775 /// </param>776 /// <param name="destinationPath">777 /// The path to the item to which the property should be moved.778 /// </param>779 /// <param name="destinationProperty">780 /// The name of the property that should be moved to.781 /// </param>782 /// <param name="cmdletProviderContext">783 /// The context under which this method is being called.784 /// </param>785 /// <remarks>786 /// Implement this method when you are providing access to a data store787 /// that allows dynamic moving of properties.788 /// </remarks>789 internal void MoveProperty(790 string sourcePath,791 string sourceProperty,792 string destinationPath,793 string destinationProperty,794 CmdletProviderContext cmdletProviderContext)795 {796 Context = cmdletProviderContext;797 798 if (this is not IDynamicPropertyCmdletProvider propertyProvider)799 {800 throw801 PSTraceSource.NewNotSupportedException(802 SessionStateStrings.IDynamicPropertyCmdletProvider_NotSupported);803 }804 805 // Call interface method806 807 propertyProvider.MoveProperty(sourcePath, sourceProperty, destinationPath, destinationProperty);808 }809 810 /// <summary>811 /// Gives the provider a chance to attach additional parameters to812 /// the move-itemproperty cmdlet.813 /// </summary>814 /// <param name="path">815 /// If the path was specified on the command line, this is the path816 /// to the item to get the dynamic parameters for.817 /// </param>818 /// <param name="sourceProperty">819 /// The name of the property that should be copied.820 /// </param>821 /// <param name="destinationPath">822 /// The path to the item to which the property should be copied.823 /// </param>824 /// <param name="destinationProperty">825 /// The name of the property that should be copied to.826 /// </param>827 /// <param name="cmdletProviderContext">828 /// The context under which this method is being called.829 /// </param>830 /// <returns>831 /// An object that has properties and fields decorated with832 /// parsing attributes similar to a cmdlet class.833 /// </returns>834 internal object MovePropertyDynamicParameters(835 string path,836 string sourceProperty,837 string destinationPath,838 string destinationProperty,839 CmdletProviderContext cmdletProviderContext)840 {841 Context = cmdletProviderContext;842 843 if (this is not IDynamicPropertyCmdletProvider propertyProvider)844 {845 return null;846 }847 848 return propertyProvider.MovePropertyDynamicParameters(path, sourceProperty, destinationPath, destinationProperty);849 }850 851 #endregion IDynamicPropertyCmdletProvider method wrappers852 853 #region IContentCmdletProvider method wrappers854 855 /// <summary>856 /// Internal wrapper for the GetContentReader protected method. This method will857 /// only be called if the provider implements the IContentCmdletProvider interface.858 /// </summary>859 /// <param name="path">860 /// The path to the item to retrieve content from.861 /// </param>862 /// <param name="cmdletProviderContext">863 /// The context under which this method is being called.864 /// </param>865 /// <returns>866 /// An instance of the IContentReader for the specified path.867 /// </returns>868 internal IContentReader GetContentReader(869 string path,870 CmdletProviderContext cmdletProviderContext)871 {872 Context = cmdletProviderContext;873 874 if (this is not IContentCmdletProvider contentProvider)875 {876 throw877 PSTraceSource.NewNotSupportedException(878 SessionStateStrings.IContentCmdletProvider_NotSupported);879 }880 881 // Call interface method882 883 return contentProvider.GetContentReader(path);884 }885 886 /// <summary>887 /// Gives the provider a chance to attach additional parameters to888 /// the get-content cmdlet.889 /// </summary>890 /// <param name="path">891 /// If the path was specified on the command line, this is the path892 /// to the item to get the dynamic parameters for.893 /// </param>894 /// <param name="cmdletProviderContext">895 /// The context under which this method is being called.896 /// </param>897 /// <returns>898 /// An object that has properties and fields decorated with899 /// parsing attributes similar to a cmdlet class.900 /// </returns>901 internal object GetContentReaderDynamicParameters(902 string path,903 CmdletProviderContext cmdletProviderContext)904 {905 Context = cmdletProviderContext;906 907 if (this is not IContentCmdletProvider contentProvider)908 {909 return null;910 }911 912 return contentProvider.GetContentReaderDynamicParameters(path);913 }914 915 /// <summary>916 /// Internal wrapper for the GetContentWriter protected method. This method will917 /// only be called if the provider implements the IContentCmdletProvider interface.918 /// </summary>919 /// <param name="path">920 /// The path to the item to set content on.921 /// </param>922 /// <param name="cmdletProviderContext">923 /// The context under which this method is being called.924 /// </param>925 /// <returns>926 /// An instance of the IContentWriter for the specified path.927 /// </returns>928 internal IContentWriter GetContentWriter(929 string path,930 CmdletProviderContext cmdletProviderContext)931 {932 Context = cmdletProviderContext;933 934 if (this is not IContentCmdletProvider contentProvider)935 {936 throw937 PSTraceSource.NewNotSupportedException(938 SessionStateStrings.IContentCmdletProvider_NotSupported);939 }940 941 // Call interface method942 943 return contentProvider.GetContentWriter(path);944 }945 946 /// <summary>947 /// Gives the provider a chance to attach additional parameters to948 /// the add-content and set-content cmdlet.949 /// </summary>950 /// <param name="path">951 /// If the path was specified on the command line, this is the path952 /// to the item to get the dynamic parameters for.953 /// </param>954 /// <param name="cmdletProviderContext">955 /// The context under which this method is being called.956 /// </param>957 /// <returns>958 /// An object that has properties and fields decorated with959 /// parsing attributes similar to a cmdlet class.960 /// </returns>961 internal object GetContentWriterDynamicParameters(962 string path,963 CmdletProviderContext cmdletProviderContext)964 {965 Context = cmdletProviderContext;966 967 if (this is not IContentCmdletProvider contentProvider)968 {969 return null;970 }971 972 return contentProvider.GetContentWriterDynamicParameters(path);973 }974 975 /// <summary>976 /// Internal wrapper for the ClearContent protected method. This method will977 /// only be called if the provider implements the IContentCmdletProvider interface.978 /// </summary>979 /// <param name="path">980 /// The path to the item to clear the content from.981 /// </param>982 /// <param name="cmdletProviderContext">983 /// The context under which this method is being called.984 /// </param>985 internal void ClearContent(986 string path,987 CmdletProviderContext cmdletProviderContext)988 {989 Context = cmdletProviderContext;990 991 if (this is not IContentCmdletProvider contentProvider)992 {993 throw994 PSTraceSource.NewNotSupportedException(995 SessionStateStrings.IContentCmdletProvider_NotSupported);996 }997 998 // Call interface method999 1000 contentProvider.ClearContent(path);1001 }1002 1003 /// <summary>1004 /// Gives the provider a chance to attach additional parameters to1005 /// the clear-content cmdlet.1006 /// </summary>1007 /// <param name="path">1008 /// If the path was specified on the command line, this is the path1009 /// to the item to get the dynamic parameters for.1010 /// </param>1011 /// <param name="cmdletProviderContext">1012 /// The context under which this method is being called.1013 /// </param>1014 /// <returns>1015 /// An object that has properties and fields decorated with1016 /// parsing attributes similar to a cmdlet class.1017 /// </returns>1018 internal object ClearContentDynamicParameters(1019 string path,1020 CmdletProviderContext cmdletProviderContext)1021 {1022 Context = cmdletProviderContext;1023 1024 if (this is not IContentCmdletProvider contentProvider)1025 {1026 return null;1027 }1028 1029 return contentProvider.ClearContentDynamicParameters(path);1030 }1031 1032 #endregion IContentCmdletProvider method wrappers1033 1034 #endregion internal members1035 1036 #region protected members1037 1038 /// <summary>1039 /// Gives the provider the opportunity to initialize itself.1040 /// </summary>1041 /// <param name="providerInfo">1042 /// The information about the provider that is being started.1043 /// </param>1044 /// <remarks>1045 /// The default implementation returns the ProviderInfo instance that1046 /// was passed.1047 ///1048 /// To have session state maintain persisted data on behalf of the provider,1049 /// the provider should derive from <see cref="System.Management.Automation.ProviderInfo"/>1050 /// and add any properties or1051 /// methods for the data it wishes to persist. When Start gets called the1052 /// provider should construct an instance of its derived ProviderInfo using the1053 /// providerInfo that is passed in and return that new instance.1054 /// </remarks>1055 protected virtual ProviderInfo Start(ProviderInfo providerInfo)1056 {1057 using (PSTransactionManager.GetEngineProtectionScope())1058 {1059 return providerInfo;1060 }1061 }1062 1063 /// <summary>1064 /// Gets an object that defines the additional parameters for the Start implementation1065 /// for a provider.1066 /// </summary>1067 /// <returns>1068 /// Overrides of this method should return an object that has properties and fields decorated with1069 /// parsing attributes similar to a cmdlet class or a1070 /// <see cref="System.Management.Automation.RuntimeDefinedParameterDictionary"/>.1071 ///1072 /// The default implementation returns null. (no additional parameters)1073 /// </returns>1074 protected virtual object StartDynamicParameters()1075 {1076 using (PSTransactionManager.GetEngineProtectionScope())1077 {1078 return null;1079 }1080 }1081 1082 /// <summary>1083 /// Called by session state when the provider is being removed.1084 /// </summary>1085 /// <remarks>1086 /// A provider should override this method to free up any resources that the provider1087 /// was using.1088 ///1089 /// The default implementation does nothing.1090 /// </remarks>1091 protected virtual void Stop()1092 {1093 using (PSTransactionManager.GetEngineProtectionScope())1094 {1095 }1096 }1097 1098 /// <summary>1099 /// Indicates whether stop has been requested on this provider.1100 /// </summary>1101 public bool Stopping1102 {1103 get1104 {1105 using (PSTransactionManager.GetEngineProtectionScope())1106 {1107 Diagnostics.Assert(1108 Context != null,1109 "The context should always be set");1110 1111 return Context.Stopping;1112 }1113 }1114 }1115 1116 /// <summary>1117 /// Gets the instance of session state for the current runspace.1118 /// </summary>1119 public SessionState SessionState1120 {1121 get1122 {1123 using (PSTransactionManager.GetEngineProtectionScope())1124 {1125 Diagnostics.Assert(1126 Context != null,1127 "The context should always be set");1128 1129 return new SessionState(Context.ExecutionContext.EngineSessionState);1130 }1131 }1132 }1133 1134 /// <summary>1135 /// Gets the instance of the provider interface APIs for the current runspace.1136 /// </summary>1137 public ProviderIntrinsics InvokeProvider1138 {1139 get1140 {1141 using (PSTransactionManager.GetEngineProtectionScope())1142 {1143 Diagnostics.Assert(1144 Context != null,1145 "The context should always be set");1146 1147 return new ProviderIntrinsics(Context.ExecutionContext.EngineSessionState);1148 }1149 }1150 }1151 1152 /// <summary>1153 /// Gets the instance of the command invocation APIs for the current runspace.1154 /// </summary>1155 public CommandInvocationIntrinsics InvokeCommand1156 {1157 get1158 {1159 using (PSTransactionManager.GetEngineProtectionScope())1160 {1161 Diagnostics.Assert(1162 Context != null,1163 "The context should always be set");1164 1165 return new CommandInvocationIntrinsics(Context.ExecutionContext);1166 }1167 }1168 }1169 1170 /// <summary>1171 /// Gets the credentials under which the operation should run.1172 /// </summary>1173 public PSCredential Credential1174 {1175 get1176 {1177 using (PSTransactionManager.GetEngineProtectionScope())1178 {1179 Diagnostics.Assert(1180 Context != null,1181 "The context should always be set");1182 1183 return Context.Credential;1184 }1185 }1186 }1187 1188 /// <summary>1189 /// The information about the provider that is stored in the runspace1190 /// on behalf of the provider.1191 /// </summary>1192 /// <remarks>1193 /// If a derived type of ProviderInfo was returned from the Start method, it1194 /// will be set here in all subsequent calls to the provider.1195 /// </remarks>1196 protected internal ProviderInfo ProviderInfo1197 {1198 get1199 {1200 using (PSTransactionManager.GetEngineProtectionScope())