Set-TraceSource parameter -Option has default value 'None' and not 'All'.

[jhribal]

PR Summary

In all versions (5.1, 7.2, 7.4, 7.5) i changed mentioned Set-TraceSource default value for parameter -Option. In current documentation is stated that the default value is All but is actually None.

I found this when i executed cmdlet Set-TraceSource -Name * -PSHost without explicit value for parameter -Option (expected it will be All by default as stated in documentation) but no tracing information was shown when i executed further commands. If i explicitly set the -Option parameter everything is fine.

Here is link for 7.4 where doc says that the default value is All https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/set-tracesource?view=powershell-7.4#-option.

I went to explore the source code to be sure and it seems to me that one of these things should happen:

1. Accept this commit that changes the documentation and voluntarily change the line private PSTraceSourceOptions _options = PSTraceSourceOptions.All; to private PSTraceSourceOptions _options = PSTraceSourceOptions.None; because the initially set value PSTraceSourceOptions.All is actually never used. You have to explicitly set -Option parameter otherwise _options variable is not used thanks to the if (optionsSpecified) condition. But in that case you overwrite the initially set value PSTraceSourceOptions.All so there is no reason to set it as initial value for variable _options. It makes more sense to set it to PSTraceSourceOptions.None.
2. Don't accept this commit and remove the condition from this block of code if (optionsSpecified) { SetFlags(matchingSources); } so it is not necessary to explicitly set -Option parameter and the default value for this parameter will be trully PSTraceSourceOptions.All. But this may theoretically lead to problems if anybody uses the Set-TraceSource cmdlet without -Option parameter (don't know if it makes sense) because then tracing will magically start to appear.

https://github.com/PowerShell/PowerShell/blob/2f4f585e7fe075f5c1669397ae738c554fa18391/src/Microsoft.PowerShell.Commands.Utility/commands/utility/trace/TraceListenerCommandBase.cs#L47

  /// <summary>
  /// The flags to be set on the TraceSource.
  /// </summary>
  /// <value></value>
  internal PSTraceSourceOptions OptionsInternal
  {
      get
      {
          return _options;
      }

      set
      {
          _options = value;
          optionsSpecified = true;
      }
  }

  private PSTraceSourceOptions _options = PSTraceSourceOptions.All;

Somewhere later in the file we can see that the initial value PSTraceSourceOptions.All from variable _options is actually never used if it is not explictly specified via cmdlet -Option parameter.

        if (preConfigure)
        {
            // Set the flags if they were specified
            if (optionsSpecified)
            {
                SetFlags(matchingSources);
            }

            AddTraceListenersToSources(matchingSources);
            SetTraceListenerOptions(matchingSources);
        }

        /// <summary>
        /// Sets the flags for all the specified TraceSources.
        /// </summary>
        internal void SetFlags(Collection<PSTraceSource> matchingSources)
        {
            foreach (PSTraceSource structuredSource in matchingSources)
            {
                structuredSource.Options = this.OptionsInternal;
            }
        }

PR Checklist

• [X] Descriptive Title: This PR's title is a synopsis of the changes it proposes.
• [X] Summary: This PR's summary describes the scope and intent of the change.
• [X] Contributor's Guide: I have read the contributors guide.
• [X] Style: This PR adheres to the style guide.

[learn-build-service-prod[bot]]

Learn Build status updates of commit 8ec0506:

:white_check_mark: Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md	:white_check_mark:Succeeded	View (powershell-5.1)
reference/7.2/Microsoft.PowerShell.Utility/Set-TraceSource.md	:white_check_mark:Succeeded	View (powershell-7.2)
reference/7.4/Microsoft.PowerShell.Utility/Set-TraceSource.md	:white_check_mark:Succeeded	View (powershell-7.4)
reference/7.5/Microsoft.PowerShell.Utility/Set-TraceSource.md	:white_check_mark:Succeeded	View (powershell-7.5)

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[github-actions[bot]]

Expectations

Thanks for your submission! Here's a quick note to provide you with some context for what to expect from the docs team and the process now that you've submitted a PR. Even if you've contributed to this repo before, we strongly suggest reading this information; it might have changed since you last read it.

To see our process for reviewing PRs, please read our editor's checklist and process for managing pull requests in particular. Below is a brief, high-level summary of what to expect, but our contributor guide has expanded details.

The docs team begins to review your PR if you request them to or if your PR meets these conditions:

• It is not a draft PR.
• It does not have a WIP prefix in the title.
• It passes validation and build steps.
• It does not have any merge conflicts.
• You have checked every box in the PR Checklist, indicating you have completed all required steps and marked your PR as Ready to Merge.

You can always request a review at any stage in your authoring process, the docs team is here to help! You do not need to submit a fully polished and finished draft; the docs team can help you get content ready for merge.

While reviewing your PR, the docs team may make suggestions, write comments, and ask questions. When all requirements are satisfied, the docs team marks your PR as Approved and merges it. Once your PR is merged, it is included the next time the documentation is published. For this project, the documentation is published daily at 3 p.m. Pacific Standard Time (PST).