mirror of
https://github.com/aphrody-labs/PowerShell.git
synced 2026-10-15 14:20:03 +00:00
430 lines
16 KiB
C#
430 lines
16 KiB
C#
/********************************************************************++
|
|
Copyright (c) Microsoft Corporation. All rights reserved.
|
|
--********************************************************************/
|
|
|
|
using System.IO;
|
|
using System.Collections;
|
|
using System.Collections.Generic;
|
|
using System.Collections.ObjectModel;
|
|
using System.Globalization;
|
|
using System.Xml;
|
|
using System.Reflection;
|
|
|
|
namespace System.Management.Automation
|
|
{
|
|
/// <summary>
|
|
/// Class ProviderHelpProvider implement the help provider for commands.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Provider Help information are stored in 'help.xml' files. Location of these files
|
|
/// can be found from CommandDiscovery.
|
|
/// </remarks>
|
|
internal class ProviderHelpProvider: HelpProviderWithCache
|
|
{
|
|
/// <summary>
|
|
/// Constructor for HelpProvider
|
|
/// </summary>
|
|
internal ProviderHelpProvider(HelpSystem helpSystem) : base(helpSystem)
|
|
{
|
|
_sessionState = helpSystem.ExecutionContext.SessionState;
|
|
}
|
|
|
|
private readonly SessionState _sessionState;
|
|
|
|
#region Common Properties
|
|
|
|
/// <summary>
|
|
/// Name of this help provider.
|
|
/// </summary>
|
|
/// <value>Name of this help provider.</value>
|
|
override internal string Name
|
|
{
|
|
get
|
|
{
|
|
return "Provider Help Provider";
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// Help category of this provider.
|
|
/// </summary>
|
|
/// <value>Help category of this provider</value>
|
|
override internal HelpCategory HelpCategory
|
|
{
|
|
get
|
|
{
|
|
return HelpCategory.Provider;
|
|
}
|
|
}
|
|
|
|
#endregion
|
|
|
|
#region Help Provider Interface
|
|
|
|
/// <summary>
|
|
/// Do exact match help based on the target.
|
|
/// </summary>
|
|
/// <param name="helpRequest">help request object</param>
|
|
override internal IEnumerable<HelpInfo> ExactMatchHelp(HelpRequest helpRequest)
|
|
{
|
|
Collection<ProviderInfo> matchingProviders = null;
|
|
|
|
try
|
|
{
|
|
matchingProviders = this._sessionState.Provider.Get(helpRequest.Target);
|
|
}
|
|
catch (ProviderNotFoundException e)
|
|
{
|
|
// We distinguish two cases here,
|
|
// a. If the "Provider" is the only category to search for in this case,
|
|
// an error will be written.
|
|
// b. Otherwise, no errors will be written since in end user's mind,
|
|
// he may mean to search for provider help.
|
|
if (this.HelpSystem.LastHelpCategory == HelpCategory.Provider)
|
|
{
|
|
ErrorRecord errorRecord = new ErrorRecord(e, "ProviderLoadError", ErrorCategory.ResourceUnavailable, null);
|
|
errorRecord.ErrorDetails = new ErrorDetails(typeof(ProviderHelpProvider).GetTypeInfo().Assembly, "HelpErrors", "ProviderLoadError", helpRequest.Target, e.Message);
|
|
this.HelpSystem.LastErrors.Add(errorRecord);
|
|
}
|
|
}
|
|
|
|
if (matchingProviders != null)
|
|
{
|
|
foreach (ProviderInfo providerInfo in matchingProviders)
|
|
{
|
|
try
|
|
{
|
|
LoadHelpFile(providerInfo);
|
|
}
|
|
catch (IOException ioException)
|
|
{
|
|
ReportHelpFileError(ioException, helpRequest.Target, providerInfo.HelpFile);
|
|
}
|
|
catch (System.Security.SecurityException securityException)
|
|
{
|
|
ReportHelpFileError(securityException, helpRequest.Target, providerInfo.HelpFile);
|
|
}
|
|
catch (XmlException xmlException)
|
|
{
|
|
ReportHelpFileError(xmlException, helpRequest.Target, providerInfo.HelpFile);
|
|
}
|
|
|
|
HelpInfo helpInfo = GetCache(providerInfo.PSSnapInName + "\\" + providerInfo.Name);
|
|
|
|
if (helpInfo != null)
|
|
{
|
|
yield return helpInfo;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
static private string GetProviderAssemblyPath(ProviderInfo providerInfo)
|
|
{
|
|
if (providerInfo == null)
|
|
return null;
|
|
|
|
if (providerInfo.ImplementingType == null)
|
|
return null;
|
|
|
|
return Path.GetDirectoryName(providerInfo.ImplementingType.GetTypeInfo().Assembly.Location);
|
|
}
|
|
|
|
/// <summary>
|
|
/// This is a hashtable to track which help files are loaded already.
|
|
///
|
|
/// This will avoid one help file getting loaded again and again.
|
|
/// (Which should not happen unless some provider is pointing
|
|
/// to a help file that actually doesn't contain the help for it).
|
|
///
|
|
/// </summary>
|
|
private readonly Hashtable _helpFiles = new Hashtable();
|
|
|
|
/// <summary>
|
|
/// Load help file provided.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// This will load providerHelpInfo from help file into help cache.
|
|
/// </remarks>
|
|
/// <param name="providerInfo">providerInfo for which to locate help.</param>
|
|
private void LoadHelpFile(ProviderInfo providerInfo)
|
|
{
|
|
if (providerInfo == null)
|
|
{
|
|
throw PSTraceSource.NewArgumentNullException("providerInfo");
|
|
}
|
|
|
|
string helpFile = providerInfo.HelpFile;
|
|
|
|
if (String.IsNullOrEmpty(helpFile) || _helpFiles.Contains(helpFile))
|
|
{
|
|
return;
|
|
}
|
|
|
|
string helpFileToLoad = helpFile;
|
|
|
|
// Get the mshsnapinfo object for this cmdlet.
|
|
PSSnapInInfo mshSnapInInfo = providerInfo.PSSnapIn;
|
|
|
|
// Search fallback
|
|
// 1. If PSSnapInInfo exists, then always look in the application base
|
|
// of the mshsnapin
|
|
// Otherwise,
|
|
// Look in the default search path and cmdlet assembly path
|
|
Collection<String> searchPaths = new Collection<String>();
|
|
if (mshSnapInInfo != null)
|
|
{
|
|
Diagnostics.Assert(!string.IsNullOrEmpty(mshSnapInInfo.ApplicationBase),
|
|
"Application Base is null or empty.");
|
|
// not minishell case..
|
|
// we have to search only in the application base for a mshsnapin...
|
|
// if you create an absolute path for helpfile, then MUIFileSearcher
|
|
// will look only in that path.
|
|
helpFileToLoad = Path.Combine(mshSnapInInfo.ApplicationBase, helpFile);
|
|
}
|
|
else if ((providerInfo.Module != null) && (!string.IsNullOrEmpty(providerInfo.Module.Path)))
|
|
{
|
|
helpFileToLoad = Path.Combine(providerInfo.Module.ModuleBase, helpFile);
|
|
}
|
|
else
|
|
{
|
|
searchPaths.Add(GetDefaultShellSearchPath());
|
|
searchPaths.Add(GetProviderAssemblyPath(providerInfo));
|
|
}
|
|
|
|
string location = MUIFileSearcher.LocateFile(helpFileToLoad, searchPaths);
|
|
if (String.IsNullOrEmpty(location))
|
|
throw new FileNotFoundException(helpFile);
|
|
|
|
XmlDocument doc = InternalDeserializer.LoadUnsafeXmlDocument(
|
|
new FileInfo(location),
|
|
false, /* ignore whitespace, comments, etc. */
|
|
null); /* default maxCharactersInDocument */
|
|
|
|
// Add this file into _helpFiles hashtable to prevent it to be loaded again.
|
|
_helpFiles[helpFile] = 0;
|
|
|
|
XmlNode helpItemsNode = null;
|
|
|
|
if (doc.HasChildNodes)
|
|
{
|
|
for (int i = 0; i < doc.ChildNodes.Count; i++)
|
|
{
|
|
XmlNode node = doc.ChildNodes[i];
|
|
if (node.NodeType == XmlNodeType.Element && String.Compare(node.Name, "helpItems", StringComparison.OrdinalIgnoreCase) == 0)
|
|
{
|
|
helpItemsNode = node;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
if (helpItemsNode == null)
|
|
return;
|
|
|
|
using (this.HelpSystem.Trace(location))
|
|
{
|
|
if (helpItemsNode.HasChildNodes)
|
|
{
|
|
for (int i = 0; i < helpItemsNode.ChildNodes.Count; i++)
|
|
{
|
|
XmlNode node = helpItemsNode.ChildNodes[i];
|
|
if (node.NodeType == XmlNodeType.Element && String.Compare(node.Name, "providerHelp", StringComparison.OrdinalIgnoreCase) == 0)
|
|
{
|
|
HelpInfo helpInfo = ProviderHelpInfo.Load(node);
|
|
|
|
if (helpInfo != null)
|
|
{
|
|
this.HelpSystem.TraceErrors(helpInfo.Errors);
|
|
// Add snapin qualified type name for this command..
|
|
// this will enable customizations of the help object.
|
|
helpInfo.FullHelp.TypeNames.Insert(0, string.Format(CultureInfo.InvariantCulture,
|
|
"ProviderHelpInfo#{0}#{1}", providerInfo.PSSnapInName, helpInfo.Name));
|
|
|
|
if (!string.IsNullOrEmpty(providerInfo.PSSnapInName))
|
|
{
|
|
helpInfo.FullHelp.Properties.Add(new PSNoteProperty("PSSnapIn", providerInfo.PSSnapIn));
|
|
helpInfo.FullHelp.TypeNames.Insert(1, string.Format(CultureInfo.InvariantCulture,
|
|
"ProviderHelpInfo#{0}", providerInfo.PSSnapInName));
|
|
}
|
|
AddCache(providerInfo.PSSnapInName+"\\"+helpInfo.Name, helpInfo);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// Search for provider help based on a search target.
|
|
/// </summary>
|
|
/// <param name="helpRequest">help request object</param>
|
|
/// <param name="searchOnlyContent">
|
|
/// If true, searches for pattern in the help content. Individual
|
|
/// provider can decide which content to search in.
|
|
///
|
|
/// If false, seraches for pattern in the command names.
|
|
/// </param>
|
|
/// <returns></returns>
|
|
override internal IEnumerable<HelpInfo> SearchHelp(HelpRequest helpRequest, bool searchOnlyContent)
|
|
{
|
|
int countOfHelpInfoObjectsFound = 0;
|
|
string target = helpRequest.Target;
|
|
string pattern = target;
|
|
// this will be used only when searchOnlyContent == true
|
|
WildcardPattern wildCardPattern = null;
|
|
|
|
bool decoratedSearch = !WildcardPattern.ContainsWildcardCharacters(target);
|
|
|
|
if (!searchOnlyContent)
|
|
{
|
|
if (decoratedSearch)
|
|
{
|
|
pattern += "*";
|
|
}
|
|
}
|
|
else
|
|
{
|
|
string searchTarget = helpRequest.Target;
|
|
if (decoratedSearch)
|
|
{
|
|
searchTarget = "*" + helpRequest.Target + "*";
|
|
}
|
|
|
|
wildCardPattern = WildcardPattern.Get(searchTarget, WildcardOptions.Compiled | WildcardOptions.IgnoreCase);
|
|
// search in all providers
|
|
pattern = "*";
|
|
}
|
|
|
|
PSSnapinQualifiedName snapinQualifiedNameForPattern =
|
|
PSSnapinQualifiedName.GetInstance(pattern);
|
|
|
|
if (null == snapinQualifiedNameForPattern)
|
|
{
|
|
yield break;
|
|
}
|
|
|
|
foreach (ProviderInfo providerInfo in this._sessionState.Provider.GetAll())
|
|
{
|
|
if (providerInfo.IsMatch(pattern))
|
|
{
|
|
try
|
|
{
|
|
LoadHelpFile(providerInfo);
|
|
}
|
|
catch (IOException ioException)
|
|
{
|
|
if (!decoratedSearch)
|
|
{
|
|
ReportHelpFileError(ioException, providerInfo.Name, providerInfo.HelpFile);
|
|
}
|
|
}
|
|
catch (System.Security.SecurityException securityException)
|
|
{
|
|
if (!decoratedSearch)
|
|
{
|
|
ReportHelpFileError(securityException, providerInfo.Name, providerInfo.HelpFile);
|
|
}
|
|
}
|
|
catch (XmlException xmlException)
|
|
{
|
|
if (!decoratedSearch)
|
|
{
|
|
ReportHelpFileError(xmlException, providerInfo.Name, providerInfo.HelpFile);
|
|
}
|
|
}
|
|
|
|
HelpInfo helpInfo = GetCache(providerInfo.PSSnapInName + "\\" + providerInfo.Name);
|
|
|
|
if (helpInfo != null)
|
|
{
|
|
if (searchOnlyContent)
|
|
{
|
|
// ignore help objects that do not have pattern in its help
|
|
// content.
|
|
if (!helpInfo.MatchPatternInContent(wildCardPattern))
|
|
{
|
|
continue;
|
|
}
|
|
}
|
|
|
|
countOfHelpInfoObjectsFound++;
|
|
yield return helpInfo;
|
|
|
|
if (countOfHelpInfoObjectsFound >= helpRequest.MaxResults && helpRequest.MaxResults > 0)
|
|
yield break;
|
|
}
|
|
}
|
|
|
|
}
|
|
}
|
|
|
|
override internal IEnumerable<HelpInfo> ProcessForwardedHelp(HelpInfo helpInfo, HelpRequest helpRequest)
|
|
{
|
|
ProviderCommandHelpInfo providerCommandHelpInfo = new ProviderCommandHelpInfo(
|
|
helpInfo, helpRequest.ProviderContext);
|
|
yield return providerCommandHelpInfo;
|
|
}
|
|
#if V2
|
|
/// <summary>
|
|
/// Process a helpInfo forwarded from other providers (normally commandHelpProvider)
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// For command help info, this will
|
|
/// 1. check whether provider-specific commandlet help exists.
|
|
/// 2. merge found provider-specific help with commandlet help provided.
|
|
/// </remarks>
|
|
/// <param name="helpInfo">helpInfo forwarded in</param>
|
|
/// <param name="helpRequest">help request object</param>
|
|
/// <returns>The help info object after processing</returns>
|
|
override internal HelpInfo ProcessForwardedHelp(HelpInfo helpInfo, HelpRequest helpRequest)
|
|
{
|
|
if (helpInfo == null)
|
|
return null;
|
|
|
|
if (helpInfo.HelpCategory != HelpCategory.Command)
|
|
{
|
|
return helpInfo;
|
|
}
|
|
|
|
string providerName = helpRequest.Provider;
|
|
if (String.IsNullOrEmpty(providerName))
|
|
{
|
|
providerName = this._sessionState.Path.CurrentLocation.Provider.Name;
|
|
}
|
|
|
|
HelpRequest providerHelpRequest = helpRequest.Clone();
|
|
providerHelpRequest.Target = providerName;
|
|
|
|
ProviderHelpInfo providerHelpInfo = (ProviderHelpInfo)this.ExactMatchHelp(providerHelpRequest);
|
|
|
|
if (providerHelpInfo == null)
|
|
return null;
|
|
|
|
CommandHelpInfo commandHelpInfo = (CommandHelpInfo)helpInfo;
|
|
|
|
CommandHelpInfo result = commandHelpInfo.MergeProviderSpecificHelp(providerHelpInfo.GetCmdletHelp(commandHelpInfo.Name), providerHelpInfo.GetDynamicParameterHelp(helpRequest.DynamicParameters));
|
|
|
|
// Reset ForwardHelpCategory for the helpinfo to be returned so that it will not be forwarded back again.
|
|
result.ForwardHelpCategory = HelpCategory.None;
|
|
|
|
return result;
|
|
}
|
|
#endif
|
|
|
|
/// <summary>
|
|
/// This will reset the help cache. Normally this corresponds to a
|
|
/// help culture change.
|
|
/// </summary>
|
|
override internal void Reset()
|
|
{
|
|
base.Reset();
|
|
|
|
_helpFiles.Clear();
|
|
}
|
|
|
|
#endregion
|
|
}
|
|
}
|