MegaBites-AI/Windows-powershell
0372
1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Collections.ObjectModel;5 6using Dbg = System.Management.Automation;7 8namespace System.Management.Automation9{10 /// <summary>11 /// Exposes the path manipulation and location APIs to the Cmdlet base class.12 /// </summary>13 public sealed class PathIntrinsics14 {15 #region Constructors16 17 /// <summary>18 /// Hide the default constructor since we always require an instance of SessionState.19 /// </summary>20 private PathIntrinsics()21 {22 Dbg.Diagnostics.Assert(23 false,24 "This constructor should never be called. Only the constructor that takes an instance of SessionState should be called.");25 }26 27 /// <summary>28 /// Internal constructor for the PathIntrinsics facade.29 /// </summary>30 /// <param name="sessionState">31 /// The session for which this is a facade.32 /// </param>33 /// <remarks>34 /// This is only public for testing purposes.35 /// </remarks>36 /// <exception cref="ArgumentNullException">37 /// If <paramref name="sessionState"/> is null.38 /// </exception>39 internal PathIntrinsics(SessionStateInternal sessionState)40 {41 if (sessionState == null)42 {43 throw PSTraceSource.NewArgumentNullException(nameof(sessionState));44 }45 46 _sessionState = sessionState;47 }48 49 #endregion Constructors50 51 #region Public methods52 53 /// <summary>54 /// Gets the current location.55 /// </summary>56 /// <exception cref="InvalidOperationException">57 /// If a location has not been set yet.58 /// </exception>59 public PathInfo CurrentLocation60 {61 get62 {63 Dbg.Diagnostics.Assert(64 _sessionState != null,65 "The only constructor for this class should always set the sessionState field");66 67 return _sessionState.CurrentLocation;68 }69 }70 71 /// <summary>72 /// Gets the current location for a specific provider.73 /// </summary>74 /// <param name="providerName">75 /// The name of the provider to get the current location for.76 /// </param>77 /// <exception cref="ArgumentNullException">78 /// If <paramref name="providerName"/> is null.79 /// </exception>80 /// <exception cref="ProviderNotFoundException">81 /// If <paramref name="namespacesID"/> refers to a provider that does not exist.82 /// </exception>83 /// <exception cref="DriveNotFoundException">84 /// If a current drive cannot be found for the provider <paramref name="providerName"/>85 /// </exception>86 public PathInfo CurrentProviderLocation(string providerName)87 {88 Dbg.Diagnostics.Assert(89 _sessionState != null,90 "The only constructor for this class should always set the sessionState field");91 92 // Parameter validation is done in the session state object93 94 return _sessionState.GetNamespaceCurrentLocation(providerName);95 }96 97 /// <summary>98 /// Gets the current location for the file system provider.99 /// </summary>100 /// <exception cref="DriveNotFoundException">101 /// If a current drive cannot be found for the FileSystem provider102 /// </exception>103 public PathInfo CurrentFileSystemLocation104 {105 get106 {107 Dbg.Diagnostics.Assert(108 _sessionState != null,109 "The only constructor for this class should always set the sessionState field");110 111 return CurrentProviderLocation(_sessionState.ExecutionContext.ProviderNames.FileSystem);112 }113 }114 115 /// <summary>116 /// Changes the current location to the specified path.117 /// </summary>118 /// <param name="path">119 /// The path to change the location to. This can be either a drive-relative or provider-relative120 /// path. It cannot be a provider-internal path.121 /// </param>122 /// <returns>123 /// The path of the new current location.124 /// </returns>125 /// <exception cref="ArgumentNullException">126 /// If <paramref name="path"/> is null.127 /// </exception>128 /// <exception cref="ArgumentException">129 /// If <paramref name="path"/> does not exist, is not a container, or130 /// resolved to multiple containers.131 /// </exception>132 /// <exception cref="ProviderNotFoundException">133 /// If <paramref name="path"/> refers to a provider that does not exist.134 /// </exception>135 /// <exception cref="DriveNotFoundException">136 /// If <paramref name="path"/> refers to a drive that does not exist.137 /// </exception>138 /// <exception cref="ProviderInvocationException">139 /// If the provider associated with <paramref name="path"/> threw an140 /// exception.141 /// </exception>142 public PathInfo SetLocation(string path)143 {144 Dbg.Diagnostics.Assert(145 _sessionState != null,146 "The only constructor for this class should always set the sessionState field");147 148 // Parameter validation is done in the session state object149 150 return _sessionState.SetLocation(path);151 }152 153 /// <summary>154 /// Changes the current location to the specified path.155 /// </summary>156 /// <param name="path">157 /// The path to change the location to. This can be either a drive-relative or provider-relative158 /// path. It cannot be a provider-internal path.159 /// </param>160 /// <param name="context">161 /// The context under which the command is running.162 /// </param>163 /// <returns>164 /// The path of the new current location.165 /// </returns>166 /// <exception cref="ArgumentNullException">167 /// If <paramref name="path"/> is null.168 /// </exception>169 /// <exception cref="ArgumentException">170 /// If <paramref name="path"/> does not exist, is not a container, or171 /// resolved to multiple containers.172 /// </exception>173 /// <exception cref="ProviderNotFoundException">174 /// If <paramref name="path"/> refers to a provider that does not exist.175 /// </exception>176 /// <exception cref="DriveNotFoundException">177 /// If <paramref name="path"/> refers to a drive that does not exist.178 /// </exception>179 /// <exception cref="ProviderInvocationException">180 /// If the provider associated with <paramref name="path"/> threw an181 /// exception.182 /// </exception>183 internal PathInfo SetLocation(string path, CmdletProviderContext context)184 {185 Dbg.Diagnostics.Assert(186 _sessionState != null,187 "The only constructor for this class should always set the sessionState field");188 189 // Parameter validation is done in the session state object190 191 return _sessionState.SetLocation(path, context);192 }193 194 /// <summary>195 /// Changes the current location to the specified path.196 /// </summary>197 /// <param name="path">198 /// The path to change the location to. This can be either a drive-relative or provider-relative199 /// path. It cannot be a provider-internal path.200 /// </param>201 /// <param name="context">202 /// The context under which the command is running.203 /// </param>204 /// <param name="literalPath">205 /// Indicates if the path is a literal path.206 /// </param>207 /// <returns>208 /// The path of the new current location.209 /// </returns>210 /// <exception cref="ArgumentNullException">211 /// If <paramref name="path"/> is null.212 /// </exception>213 /// <exception cref="ArgumentException">214 /// If <paramref name="path"/> does not exist, is not a container, or215 /// resolved to multiple containers.216 /// </exception>217 /// <exception cref="ProviderNotFoundException">218 /// If <paramref name="path"/> refers to a provider that does not exist.219 /// </exception>220 /// <exception cref="DriveNotFoundException">221 /// If <paramref name="path"/> refers to a drive that does not exist.222 /// </exception>223 /// <exception cref="ProviderInvocationException">224 /// If the provider associated with <paramref name="path"/> threw an225 /// exception.226 /// </exception>227 internal PathInfo SetLocation(string path, CmdletProviderContext context, bool literalPath)228 {229 Dbg.Diagnostics.Assert(230 _sessionState != null,231 "The only constructor for this class should always set the sessionState field");232 233 // Parameter validation is done in the session state object234 235 return _sessionState.SetLocation(path, context, literalPath);236 }237 238 /// <summary>239 /// Determines if the specified path is the current location or a parent of the current location.240 /// </summary>241 /// <param name="path">242 /// A drive or provider-qualified path to be compared against the current location.243 /// </param>244 /// <param name="context">245 /// The context under which the command is running.246 /// </param>247 /// <returns>248 /// True if the path is the current location or a parent of the current location. False otherwise.249 /// </returns>250 /// <exception cref="ArgumentNullException">251 /// If <paramref name="path"/> is null.252 /// </exception>253 /// <exception cref="ProviderNotFoundException">254 /// If the path is a provider-qualified path for a provider that is255 /// not loaded into the system.256 /// </exception>257 /// <exception cref="DriveNotFoundException">258 /// If the <paramref name="path"/> refers to a drive that could not be found.259 /// </exception>260 /// <exception cref="ProviderInvocationException">261 /// If the provider used to build the path threw an exception.262 /// </exception>263 /// <exception cref="NotSupportedException">264 /// If the provider that the <paramref name="path"/> represents is not a NavigationCmdletProvider265 /// or ContainerCmdletProvider.266 /// </exception>267 /// <exception cref="InvalidOperationException">268 /// If the <paramref name="path"/> starts with "~" and the home location is not set for269 /// the provider.270 /// </exception>271 /// <exception cref="ProviderInvocationException">272 /// If the provider specified by <paramref name="providerId"/> threw an273 /// exception when its GetParentPath or MakePath was called while274 /// processing the <paramref name="path"/>.275 /// </exception>276 internal bool IsCurrentLocationOrAncestor(string path, CmdletProviderContext context)277 {278 Dbg.Diagnostics.Assert(279 _sessionState != null,280 "The only constructor for this class should always set the sessionState field");281 282 // Parameter validation is done in the session state object283 284 return _sessionState.IsCurrentLocationOrAncestor(path, context);285 }286 287 /// <summary>288 /// Pushes the current location onto the location stack so that it can be retrieved later.289 /// </summary>290 /// <param name="stackName">291 /// The ID of the stack to push the location onto.292 /// </param>293 public void PushCurrentLocation(string stackName)294 {295 Dbg.Diagnostics.Assert(296 _sessionState != null,297 "The only constructor for this class should always set the sessionState field");298 299 _sessionState.PushCurrentLocation(stackName);300 }301 302 /// <summary>303 /// Gets the location off the top of the location stack.304 /// </summary>305 /// <param name="stackName">306 /// The ID of the stack to pop the location from. If stackName is null or empty307 /// the default stack is used.308 /// </param>309 /// <returns>310 /// The path information for the location that was on the top of the location stack.311 /// </returns>312 /// <exception cref="ArgumentException">313 /// If the path on the stack does not exist, is not a container, or314 /// resolved to multiple containers.315 /// or316 /// If <paramref name="stackName"/> contains wildcard characters and resolves317 /// to multiple location stacks.318 /// or319 /// A stack was not found with the specified name.320 /// </exception>321 /// <exception cref="ProviderNotFoundException">322 /// If the path on the stack refers to a provider that does not exist.323 /// </exception>324 /// <exception cref="DriveNotFoundException">325 /// If the path on the stack refers to a drive that does not exist.326 /// </exception>327 /// <exception cref="ProviderInvocationException">328 /// If the provider associated with the path on the stack threw an329 /// exception.330 /// </exception>331 public PathInfo PopLocation(string stackName)332 {333 Dbg.Diagnostics.Assert(334 _sessionState != null,335 "The only constructor for this class should always set the sessionState field");336 337 return _sessionState.PopLocation(stackName);338 }339 340 /// <summary>341 /// Gets the location stack and all the locations on it.342 /// </summary>343 /// <param name="stackName">344 /// The stack ID of the stack to get the stack info for.345 /// </param>346 public PathInfoStack LocationStack(string stackName)347 {348 Dbg.Diagnostics.Assert(349 _sessionState != null,350 "The only constructor for this class should always set the sessionState field");351 352 return _sessionState.LocationStack(stackName);353 }354 355 /// <summary>356 /// Sets the default location stack to that specified by the stack ID.357 /// </summary>358 /// <param name="stackName">359 /// The stack ID of the stack to use as the default location stack.360 /// </param>361 /// <exception cref="ItemNotFoundException">362 /// If <paramref name="stackName"/> does not exist as a location stack.363 /// </exception>364 public PathInfoStack SetDefaultLocationStack(string stackName)365 {366 Dbg.Diagnostics.Assert(367 _sessionState != null,368 "The only constructor for this class should always set the sessionState field");369 370 return _sessionState.SetDefaultLocationStack(stackName);371 }372 373 /// <summary>374 /// Resolves a drive or provider qualified absolute or relative path that may contain375 /// wildcard characters into one or more absolute drive or provider qualified paths.376 /// </summary>377 /// <param name="path">378 /// The drive or provider qualified path to be resolved. This path may contain wildcard379 /// characters which will get resolved.380 /// </param>381 /// <returns>382 /// An array of PowerShell paths that resolved from the given path.383 /// </returns>384 /// <exception cref="ArgumentNullException">385 /// If <paramref name="path"/> is null.386 /// </exception>387 /// <exception cref="ProviderNotFoundException">388 /// If <paramref name="path"/> is a provider-qualified path389 /// and the specified provider does not exist.390 /// </exception>391 /// <exception cref="DriveNotFoundException">392 /// If <paramref name="path"/> is a drive-qualified path and393 /// the specified drive does not exist.394 /// </exception>395 /// <exception cref="ProviderInvocationException">396 /// If the provider throws an exception when its MakePath gets397 /// called.398 /// </exception>399 /// <exception cref="NotSupportedException">400 /// If the provider does not support multiple items.401 /// </exception>402 /// <exception cref="InvalidOperationException">403 /// If the home location for the provider is not set and404 /// <paramref name="path"/> starts with a "~".405 /// </exception>406 /// <exception cref="ItemNotFoundException">407 /// If <paramref name="path"/> does not contain wildcard characters and408 /// could not be found.409 /// </exception>410 public Collection<PathInfo> GetResolvedPSPathFromPSPath(string path)411 {412 // The parameters will be verified by the path resolver413 Provider.CmdletProvider providerInstance = null;414 return PathResolver.GetGlobbedMonadPathsFromMonadPath(path, false, out providerInstance);415 }416 417 /// <summary>418 /// Resolves a drive or provider qualified absolute or relative path that may contain419 /// wildcard characters into one or more absolute drive or provider qualified paths.420 /// </summary>421 /// <param name="path">422 /// The drive or provider qualified path to be resolved. This path may contain wildcard423 /// characters which will get resolved.424 /// </param>425 /// <param name="context">426 /// The context under which the command is running.427 /// </param>428 /// <returns>429 /// An array of Msh paths that resolved from the given path.430 /// </returns>431 /// <exception cref="ArgumentNullException">432 /// If <paramref name="path"/> or <paramref name="context"/> is null.433 /// </exception>434 /// <exception cref="ProviderNotFoundException">435 /// If <paramref name="path"/> is a provider-qualified path436 /// and the specified provider does not exist.437 /// </exception>438 /// <exception cref="ProviderInvocationException">439 /// If the provider throws an exception when its MakePath gets440 /// called.441 /// </exception>442 /// <exception cref="NotSupportedException">443 /// If the provider does not support multiple items.444 /// </exception>445 /// <exception cref="InvalidOperationException">446 /// If the home location for the provider is not set and447 /// <paramref name="path"/> starts with a "~".448 /// </exception>449 /// <exception cref="ItemNotFoundException">450 /// If <paramref name="path"/> does not contain wildcard characters and451 /// could not be found.452 /// </exception>453 internal Collection<PathInfo> GetResolvedPSPathFromPSPath(454 string path,455 CmdletProviderContext context)456 {457 // The parameters will be verified by the path resolver458 Provider.CmdletProvider providerInstance = null;459 return PathResolver.GetGlobbedMonadPathsFromMonadPath(path, false, context, out providerInstance);460 }461 462 /// <summary>463 /// Resolves a drive or provider qualified absolute or relative path that may contain464 /// wildcard characters into one or more provider-internal paths.465 /// </summary>466 /// <param name="path">467 /// The drive or provider qualified path to be resolved. This path may contain wildcard468 /// characters which will get resolved.469 /// </param>470 /// <param name="provider">471 /// The provider for which the returned paths should be used.472 /// </param>473 /// <returns>474 /// An array of provider-internal paths that resolved from the given path.475 /// </returns>476 /// <exception cref="ArgumentNullException">477 /// If <paramref name="path"/> is null.478 /// </exception>479 /// <exception cref="ProviderNotFoundException">480 /// If the path is a provider-qualified path for a provider that is481 /// not loaded into the system.482 /// </exception>483 /// <exception cref="DriveNotFoundException">484 /// If the <paramref name="path"/> refers to a drive that could not be found.485 /// </exception>486 /// <exception cref="ProviderInvocationException">487 /// If the provider used to build the path threw an exception.488 /// </exception>489 /// <exception cref="NotSupportedException">490 /// If the provider that the <paramref name="path"/> represents is not a NavigationCmdletProvider491 /// or ContainerCmdletProvider.492 /// </exception>493 /// <exception cref="InvalidOperationException">494 /// If the <paramref name="path"/> starts with "~" and the home location is not set for495 /// the provider.496 /// </exception>497 /// <exception cref="ProviderInvocationException">498 /// If the provider associated with the <paramref name="path"/> threw an499 /// exception when building its path.500 /// </exception>501 /// <exception cref="ItemNotFoundException">502 /// If <paramref name="path"/> does not contain wildcard characters and503 /// could not be found.504 /// </exception>505 public Collection<string> GetResolvedProviderPathFromPSPath(506 string path,507 out ProviderInfo provider)508 {509 // The parameters will be verified by the path resolver510 Provider.CmdletProvider providerInstance = null;511 return PathResolver.GetGlobbedProviderPathsFromMonadPath(path, false, out provider, out providerInstance);512 }513 514 internal Collection<string> GetResolvedProviderPathFromPSPath(515 string path,516 bool allowNonexistingPaths,517 out ProviderInfo provider)518 {519 // The parameters will be verified by the path resolver520 Provider.CmdletProvider providerInstance = null;521 return PathResolver.GetGlobbedProviderPathsFromMonadPath(path, allowNonexistingPaths, out provider, out providerInstance);522 }523 524 /// <summary>525 /// Resolves a drive or provider qualified absolute or relative path that may contain526 /// wildcard characters into one or more provider-internal paths.527 /// </summary>528 /// <param name="path">529 /// The drive or provider qualified path to be resolved. This path may contain wildcard530 /// characters which will get resolved.531 /// </param>532 /// <param name="context">533 /// The context under which the command is running.534 /// </param>535 /// <param name="provider">536 /// The provider for which the returned paths should be used.537 /// </param>538 /// <returns>539 /// An array of provider-internal paths that resolved from the given path.540 /// </returns>541 /// <exception cref="ArgumentNullException">542 /// If <paramref name="path"/> or <paramref name="context"/> is null.543 /// </exception>544 /// <exception cref="ProviderNotFoundException">545 /// If the path is a provider-qualified path for a provider that is546 /// not loaded into the system.547 /// </exception>548 /// <exception cref="DriveNotFoundException">549 /// If the <paramref name="path"/> refers to a drive that could not be found.550 /// </exception>551 /// <exception cref="ProviderInvocationException">552 /// If the provider used to build the path threw an exception.553 /// </exception>554 /// <exception cref="NotSupportedException">555 /// If the provider that the <paramref name="path"/> represents is not a NavigationCmdletProvider556 /// or ContainerCmdletProvider.557 /// </exception>558 /// <exception cref="InvalidOperationException">559 /// If the <paramref name="path"/> starts with "~" and the home location is not set for560 /// the provider.561 /// </exception>562 /// <exception cref="ProviderInvocationException">563 /// If the provider associated with the <paramref name="path"/> threw an564 /// exception when its GetParentPath or MakePath was called while565 /// processing the <paramref name="path"/>.566 /// </exception>567 /// <exception cref="ItemNotFoundException">568 /// If <paramref name="path"/> does not contain wildcard characters and569 /// could not be found.570 /// </exception>571 internal Collection<string> GetResolvedProviderPathFromPSPath(572 string path,573 CmdletProviderContext context,574 out ProviderInfo provider)575 {576 // The parameters will be verified by the path resolver577 578 Provider.CmdletProvider providerInstance = null;579 return PathResolver.GetGlobbedProviderPathsFromMonadPath(path, false, context, out provider, out providerInstance);580 }581 582 /// <summary>583 /// Resolves a drive or provider qualified absolute or relative path that may contain584 /// wildcard characters into one or more provider-internal paths.585 /// </summary>586 /// <param name="path">587 /// The drive or provider qualified path to be resolved. This path may contain wildcard588 /// characters which will get resolved.589 /// </param>590 /// <param name="providerId">591 /// The provider for which the returned paths should be used.592 /// </param>593 /// <returns>594 /// An array of provider-internal paths that resolved from the given path.595 /// </returns>596 /// <exception cref="ArgumentNullException">597 /// If <paramref name="path"/> is null.598 /// </exception>599 /// <exception cref="ProviderNotFoundException">600 /// If <paramref name="providerId"/> references a provider that does not exist.601 /// </exception>602 /// <exception cref="NotSupportedException">603 /// If the <paramref name="providerId"/> references a provider that is not604 /// a ContainerCmdletProvider.605 /// </exception>606 /// <exception cref="ProviderInvocationException">607 /// If the provider used to build the path threw an exception.608 /// </exception>609 /// <exception cref="InvalidOperationException">610 /// If the <paramref name="path"/> starts with "~" and the home location is not set for611 /// the provider.612 /// </exception>613 /// <exception cref="ItemNotFoundException">614 /// If <paramref name="path"/> does not contain wildcard characters and615 /// could not be found.616 /// </exception>617 public Collection<string> GetResolvedProviderPathFromProviderPath(618 string path,619 string providerId)620 {621 // The parameters will be verified by the path resolver622 Provider.CmdletProvider providerInstance = null;623 return PathResolver.GetGlobbedProviderPathsFromProviderPath(path, false, providerId, out providerInstance);624 }625 626 /// <summary>627 /// Resolves a drive or provider qualified absolute or relative path that may contain628 /// wildcard characters into one or more provider-internal paths.629 /// </summary>630 /// <param name="path">631 /// The drive or provider qualified path to be resolved. This path may contain wildcard632 /// characters which will get resolved.633 /// </param>634 /// <param name="context">635 /// The context under which the command is running.636 /// </param>637 /// <param name="providerId">638 /// The provider for which the returned paths should be used.639 /// </param>640 /// <returns>641 /// An array of provider-internal paths that resolved from the given path.642 /// </returns>643 /// <exception cref="ArgumentNullException">644 /// If <paramref name="path"/>, <paramref name="providerId"/>, or645 /// <paramref name="context"/> is null.646 /// </exception>647 /// <exception cref="ProviderNotFoundException">648 /// If <paramref name="providerId"/> references a provider that does not exist.649 /// </exception>650 /// <exception cref="NotSupportedException">651 /// If the <paramref name="providerId"/> references a provider that is not652 /// a ContainerCmdletProvider.653 /// </exception>654 /// <exception cref="ProviderInvocationException">655 /// If the provider used to build the path threw an exception.656 /// </exception>657 /// <exception cref="InvalidOperationException">658 /// If the <paramref name="path"/> starts with "~" and the home location is not set for659 /// the provider.660 /// </exception>661 /// <exception cref="ItemNotFoundException">662 /// If <paramref name="path"/> does not contain wildcard characters and663 /// could not be found.664 /// </exception>665 internal Collection<string> GetResolvedProviderPathFromProviderPath(666 string path,667 string providerId,668 CmdletProviderContext context)669 {670 // The parameters will be verified by the path resolver671 672 Provider.CmdletProvider providerInstance = null;673 return PathResolver.GetGlobbedProviderPathsFromProviderPath(path, false, providerId, context, out providerInstance);674 }675 676 /// <summary>677 /// Converts a drive or provider qualified absolute or relative path that may contain678 /// wildcard characters into one a provider-internal path still containing the wildcard characters.679 /// </summary>680 /// <param name="path">681 /// The drive or provider qualified path to be converted. This path may contain wildcard682 /// characters which will not get resolved.683 /// </param>684 /// <returns>685 /// A provider-internal path that does not have the wildcard characters resolved.686 /// </returns>687 /// <exception cref="ArgumentNullException">688 /// If <paramref name="path"/> is null.689 /// </exception>690 /// <exception cref="ProviderNotFoundException">691 /// If the path is a provider-qualified path for a provider that is692 /// not loaded into the system.693 /// </exception>694 /// <exception cref="DriveNotFoundException">695 /// If the <paramref name="path"/> refers to a drive that could not be found.696 /// </exception>697 /// <exception cref="ProviderInvocationException">698 /// If the provider used to build the path threw an exception.699 /// </exception>700 /// <exception cref="NotSupportedException">701 /// If the provider that the <paramref name="path"/> represents is not a NavigationCmdletProvider702 /// or ContainerCmdletProvider.703 /// </exception>704 /// <exception cref="InvalidOperationException">705 /// If the <paramref name="path"/> starts with "~" and the home location is not set for706 /// the provider.707 /// </exception>708 /// <exception cref="ProviderInvocationException">709 /// If the provider specified by <paramref name="path"/> threw an710 /// exception.711 /// </exception>712 public string GetUnresolvedProviderPathFromPSPath(string path)713 {714 // The parameters will be verified by the path resolver715 716 return PathResolver.GetProviderPath(path);717 }718 719 /// <summary>720 /// Converts a drive or provider qualified absolute or relative path that may contain721 /// wildcard characters into one a provider-internal path still containing the wildcard characters.722 /// </summary>723 /// <param name="path">724 /// The drive or provider qualified path to be converted. This path may contain wildcard725 /// characters which will not get resolved.726 /// </param>727 /// <param name="provider">728 /// The information for the provider for which the returned path should be used.729 /// </param>730 /// <param name="drive">731 /// The drive of the PowerShell path that was used to convert the path. Note, this may be null732 /// if the <paramref name="path"/> was a provider-qualified path.733 /// </param>734 /// <returns>735 /// A provider-internal path that does not have the wildcard characters resolved.736 /// </returns>737 /// <exception cref="ArgumentNullException">738 /// If <paramref name="path"/> or <paramref name="context"/> is null.739 /// </exception>740 /// <exception cref="ProviderNotFoundException">741 /// If the path is a provider-qualified path for a provider that is742 /// not loaded into the system.743 /// </exception>744 /// <exception cref="DriveNotFoundException">745 /// If the <paramref name="path"/> refers to a drive that could not be found.746 /// </exception>747 /// <exception cref="ProviderInvocationException">748 /// If the provider used to build the path threw an exception.749 /// </exception>750 /// <exception cref="NotSupportedException">751 /// If the provider that the <paramref name="path"/> represents is not a NavigationCmdletProvider752 /// or ContainerCmdletProvider.753 /// </exception>754 /// <exception cref="InvalidOperationException">755 /// If the <paramref name="path"/> starts with "~" and the home location is not set for756 /// the provider.757 /// </exception>758 /// <exception cref="ProviderInvocationException">759 /// If the provider specified by <paramref name="provider"/> threw an760 /// exception when its GetParentPath or MakePath was called while761 /// processing the <paramref name="path"/>.762 /// </exception>763 public string GetUnresolvedProviderPathFromPSPath(764 string path,765 out ProviderInfo provider,766 out PSDriveInfo drive)767 {768 CmdletProviderContext context = new CmdletProviderContext(_sessionState.ExecutionContext);769 770 // The parameters will be verified by the path resolver771 772 string result = PathResolver.GetProviderPath(path, context, out provider, out drive);773 774 context.ThrowFirstErrorOrDoNothing();775 776 return result;777 }778 779 /// <summary>780 /// Converts a drive or provider qualified absolute or relative path that may contain781 /// wildcard characters into one a provider-internal path still containing the wildcard characters.782 /// </summary>783 /// <param name="path">784 /// The drive or provider qualified path to be converted. This path may contain wildcard785 /// characters which will not get resolved.786 /// </param>787 /// <param name="context">788 /// The context under which this command is running.789 /// </param>790 /// <param name="provider">791 /// The information for the provider for which the returned path should be used.792 /// </param>793 /// <param name="drive">794 /// The drive of the Msh path that was used to convert the path.795 /// </param>796 /// <returns>797 /// A provider-internal path that does not have the wildcard characters resolved.798 /// </returns>799 /// <exception cref="ArgumentNullException">800 /// If <paramref name="path"/> or <paramref name="context"/> is null.801 /// </exception>802 /// <exception cref="ProviderNotFoundException">803 /// If the path is a provider-qualified path for a provider that is804 /// not loaded into the system.805 /// </exception>806 /// <exception cref="DriveNotFoundException">807 /// If the <paramref name="path"/> refers to a drive that could not be found.808 /// </exception>809 /// <exception cref="ProviderInvocationException">810 /// If the provider used to build the path threw an exception.811 /// </exception>812 /// <exception cref="NotSupportedException">813 /// If the provider that the <paramref name="path"/> represents is not a NavigationCmdletProvider814 /// or ContainerCmdletProvider.815 /// </exception>816 /// <exception cref="InvalidOperationException">817 /// If the <paramref name="path"/> starts with "~" and the home location is not set for818 /// the provider.819 /// </exception>820 /// <exception cref="ProviderInvocationException">821 /// If the provider specified by <paramref name="provider"/> threw an822 /// exception when its GetParentPath or MakePath was called while823 /// processing the <paramref name="path"/>.824 /// </exception>825 internal string GetUnresolvedProviderPathFromPSPath(826 string path,827 CmdletProviderContext context,828 out ProviderInfo provider,829 out PSDriveInfo drive)830 {831 // The parameters will be verified by the path resolver832 833 return PathResolver.GetProviderPath(path, context, out provider, out drive);834 }835 836 /// <summary>837 /// Determines if the give path is a PowerShell provider-qualified path.838 /// </summary>839 /// <param name="path">840 /// The path to check.841 /// </param>842 /// <returns>843 /// True if the specified path is provider-qualified, false otherwise.844 /// </returns>845 /// <remarks>846 /// A provider-qualified path is a path in the following form:847 /// providerId::provider-internal-path848 /// </remarks>849 /// <exception cref="ArgumentNullException">850 /// If <paramref name="path"/> is null.851 /// </exception>852 public bool IsProviderQualified(string path)853 {854 // The parameters will be verified by the path resolver855 856 return LocationGlobber.IsProviderQualifiedPath(path);857 }858 859 /// <summary>860 /// Determines if the given path is a drive-qualified absolute path.861 /// </summary>862 /// <param name="path">863 /// The path to check.864 /// </param>865 /// <param name="driveName">866 /// If the path is an absolute path then the returned value is867 /// the name of the drive that the path is absolute to.868 /// </param>869 /// <returns>870 /// True if the specified path is an absolute drive-qualified path.871 /// False otherwise.872 /// </returns>873 /// <remarks>874 /// A path is an absolute drive-qualified path if it has the following875 /// form:876 /// drive-name:drive-relative-path877 /// </remarks>878 /// <exception cref="ArgumentNullException">879 /// If <paramref name="path"/> is null.880 /// </exception>881 public bool IsPSAbsolute(string path, out string driveName)882 {883 // The parameters will be verified by the path resolver884 885 return PathResolver.IsAbsolutePath(path, out driveName);886 }887 888 #region Combine889 890 /// <summary>891 /// Combines two strings with a provider specific path separator.892 /// </summary>893 /// <param name="parent">894 /// The parent path to be joined with the child.895 /// </param>896 /// <param name="child">897 /// The child path to be joined with the parent.898 /// </param>899 /// <returns>900 /// The combined path of the parent and child with the provider901 /// specific path separator between them.902 /// </returns>903 /// <exception cref="ArgumentNullException">904 /// If <paramref name="context"/> is null.905 /// </exception>906 /// <exception cref="ArgumentException">907 /// If both <paramref name="parent"/> and <paramref name="child"/> is null.908 /// </exception>909 /// <exception cref="NotSupportedException">910 /// If the <paramref name="providerId"/> does not support this operation.911 /// </exception>912 /// <exception cref="PipelineStoppedException">913 /// If the pipeline is being stopped while executing the command.914 /// </exception>915 /// <exception cref="ProviderInvocationException">916 /// If the provider threw an exception.917 /// </exception>918 public string Combine(string parent, string child)919 {920 Dbg.Diagnostics.Assert(921 _sessionState != null,922 "The only constructor for this class should always set the sessionState field");923 924 // Parameter validation is done in the session state object925 926 return _sessionState.MakePath(parent, child);927 }928 929 /// <summary>930 /// Combines two strings with a provider specific path separator.931 /// </summary>932 /// <param name="parent">933 /// The parent path to be joined with the child.934 /// </param>935 /// <param name="child">936 /// The child path to be joined with the parent.937 /// </param>938 /// <param name="context">939 /// The context under which this command is running.940 /// </param>941 /// <returns>942 /// The combined path of the parent and child with the provider943 /// specific path separator between them.944 /// </returns>945 /// <exception cref="ArgumentNullException">946 /// If <paramref name="context"/> is null.947 /// </exception>948 /// <exception cref="ArgumentException">949 /// If both <paramref name="parent"/> and <paramref name="child"/> is null.950 /// </exception>951 /// <exception cref="NotSupportedException">952 /// If the <paramref name="providerId"/> does not support this operation.953 /// </exception>954 /// <exception cref="PipelineStoppedException">955 /// If the pipeline is being stopped while executing the command.956 /// </exception>957 /// <exception cref="ProviderInvocationException">958 /// If the provider threw an exception.959 /// </exception>960 internal string Combine(string parent, string child, CmdletProviderContext context)961 {962 Dbg.Diagnostics.Assert(963 _sessionState != null,964 "The only constructor for this class should always set the sessionState field");965 966 // Parameter validation is done in the session state object967 968 return _sessionState.MakePath(parent, child, context);969 }970 971 #endregion Combine972 973 #region ParseParent974 975 /// <summary>976 /// Gets the parent path of the specified path.977 /// </summary>978 /// <param name="path">979 /// The path to get the parent path from.980 /// </param>981 /// <param name="root">982 /// If the root is specified the path returned will not be any higher than the root.983 /// </param>984 /// <returns>985 /// The parent path of the specified path.986 /// </returns>987 /// <exception cref="ArgumentNullException">988 /// If <paramref name="path"/> is null.989 /// </exception>990 /// <exception cref="NotSupportedException">991 /// If the <paramref name="providerInstance"/> does not support this operation.992 /// </exception>993 /// <exception cref="PipelineStoppedException">994 /// If the pipeline is being stopped while executing the command.995 /// </exception>996 /// <exception cref="ProviderInvocationException">997 /// If the provider threw an exception.998 /// </exception>999 public string ParseParent(string path, string root)1000 {1001 Dbg.Diagnostics.Assert(1002 _sessionState != null,1003 "The only constructor for this class should always set the sessionState field");1004 1005 // Parameter validation is done in the session state object1006 1007 return _sessionState.GetParentPath(path, root);1008 }1009 1010 /// <summary>1011 /// Gets the parent path of the specified path.1012 /// </summary>1013 /// <param name="path">1014 /// The path to get the parent path from.1015 /// </param>1016 /// <param name="root">1017 /// If the root is specified the path returned will not be any higher than the root.1018 /// </param>1019 /// <param name="context">1020 /// The context under which the command is running.1021 /// </param>1022 /// <returns>1023 /// The parent path of the specified path.1024 /// </returns>1025 /// <exception cref="ArgumentNullException">1026 /// If <paramref name="path"/> is null.1027 /// </exception>1028 /// <exception cref="NotSupportedException">1029 /// If the <paramref name="providerInstance"/> does not support this operation.1030 /// </exception>1031 /// <exception cref="PipelineStoppedException">1032 /// If the pipeline is being stopped while executing the command.1033 /// </exception>1034 /// <exception cref="ProviderInvocationException">1035 /// If the provider threw an exception.1036 /// </exception>1037 internal string ParseParent(1038 string path,1039 string root,1040 CmdletProviderContext context)1041 {1042 Dbg.Diagnostics.Assert(1043 _sessionState != null,1044 "The only constructor for this class should always set the sessionState field");1045 1046 // Parameter validation is done in the session state object1047 1048 return _sessionState.GetParentPath(path, root, context, false);1049 }1050 1051 /// <summary>1052 /// Gets the parent path of the specified path.1053 /// Allow to use FileSystem as the default provider when the1054 /// given path is drive-qualified and the drive cannot be found.1055 /// </summary>1056 /// <param name="path">1057 /// The path to get the parent path from.1058 /// </param>1059 /// <param name="root">1060 /// If the root is specified the path returned will not be any higher than the root.1061 /// </param>1062 /// <param name="context">1063 /// The context under which the command is running.1064 /// </param>1065 /// <param name="useDefaultProvider">1066 /// to use default provider when needed.1067 /// </param>1068 /// <returns>1069 /// The parent path of the specified path.1070 /// </returns>1071 /// <exception cref="ArgumentNullException">1072 /// If <paramref name="path"/> is null.1073 /// </exception>1074 /// <exception cref="NotSupportedException">1075 /// If the <paramref name="providerInstance"/> does not support this operation.1076 /// </exception>1077 /// <exception cref="PipelineStoppedException">1078 /// If the pipeline is being stopped while executing the command.1079 /// </exception>1080 /// <exception cref="ProviderInvocationException">1081 /// If the provider threw an exception.1082 /// </exception>1083 internal string ParseParent(1084 string path,1085 string root,1086 CmdletProviderContext context,1087 bool useDefaultProvider)1088 {1089 Dbg.Diagnostics.Assert(1090 _sessionState != null,1091 "The only constructor for this class should always set the sessionState field");1092 1093 // Parameter validation is done in the session state object1094 1095 return _sessionState.GetParentPath(path, root, context, useDefaultProvider);1096 }1097 1098 #endregion ParseParent1099 1100 #region ParseChildName1101 1102 /// <summary>1103 /// Gets the child name of the specified path.1104 /// </summary>1105 /// <param name="path">1106 /// The path to get the child name from.1107 /// </param>1108 /// <returns>1109 /// The last element of the path.1110 /// </returns>1111 /// <exception cref="ArgumentNullException">1112 /// If <paramref name="path"/> is null.1113 /// </exception>1114 /// <exception cref="ProviderNotFoundException">1115 /// If the <paramref name="path"/> refers to a provider that could not be found.1116 /// </exception>1117 /// <exception cref="DriveNotFoundException">1118 /// If the <paramref name="path"/> refers to a drive that could not be found.1119 /// </exception>1120 /// <exception cref="NotSupportedException">1121 /// If the provider that the <paramref name="path"/> refers to does1122 /// not support this operation.1123 /// </exception>1124 /// <exception cref="ProviderInvocationException">1125 /// If the provider threw an exception.1126 /// </exception>1127 public string ParseChildName(string path)1128 {1129 Dbg.Diagnostics.Assert(1130 _sessionState != null,1131 "The only constructor for this class should always set the sessionState field");1132 1133 // Parameter validation is done in the session state object1134 1135 return _sessionState.GetChildName(path);1136 }1137 1138 /// <summary>1139 /// Gets the child name of the specified path.1140 /// </summary>1141 /// <param name="path">1142 /// The path to get the child name from.1143 /// </param>1144 /// <param name="context">1145 /// The context under which the command is running.1146 /// </param>1147 /// <returns>1148 /// The last element of the path.1149 /// </returns>1150 /// <exception cref="ArgumentNullException">1151 /// If <paramref name="path"/> is null.1152 /// </exception>1153 /// <exception cref="ProviderNotFoundException">1154 /// If the <paramref name="path"/> refers to a provider that could not be found.1155 /// </exception>1156 /// <exception cref="DriveNotFoundException">1157 /// If the <paramref name="path"/> refers to a drive that could not be found.1158 /// </exception>1159 /// <exception cref="NotSupportedException">1160 /// If the provider that the <paramref name="path"/> refers to does1161 /// not support this operation.1162 /// </exception>1163 /// <exception cref="ProviderInvocationException">1164 /// If the provider threw an exception.1165 /// </exception>1166 internal string ParseChildName(1167 string path,1168 CmdletProviderContext context)1169 {1170 Dbg.Diagnostics.Assert(1171 _sessionState != null,1172 "The only constructor for this class should always set the sessionState field");1173 1174 // Parameter validation is done in the session state object1175 1176 return _sessionState.GetChildName(path, context, false);1177 }1178 1179 /// <summary>1180 /// Gets the child name of the specified path.1181 /// Allow to use FileSystem as the default provider when the1182 /// given path is drive-qualified and the drive cannot be found.1183 /// </summary>1184 /// <param name="path">1185 /// The path to get the child name from.1186 /// </param>1187 /// <param name="context">1188 /// The context under which the command is running.1189 /// </param>1190 /// <param name="useDefaultProvider">1191 /// to use default provider when needed.1192 /// </param>1193 /// <returns>1194 /// The last element of the path.1195 /// </returns>1196 /// <exception cref="ArgumentNullException">1197 /// If <paramref name="path"/> is null.1198 /// </exception>1199 /// <exception cref="ProviderNotFoundException">1200 /// If the <paramref name="path"/> refers to a provider that could not be found.