Projectreunion: Single WinRT API to add/edit/remove Environment Variables, PATH, and PATHEXT.

[dhoehna]

Proposal:

WinRT API to manage environment variables (EVs), PATH, and PATHEXT.

Summary

A new API that would allow Centennial apps, UWP apps, and Win32 programs to append to the PATH, PATHEXT, and add/modify/remove EVs at runtime. Each change can be declared in the user/machine/ or process scope.

Rationale

• API will add tracking to PATH, PATHEXT and EVs changes when the call is from a packaged app, allowing the changes to be reverted when the packaged app is uninstalled.
• Introduces one entry point for handling PATH, PATHEXT, and EVs across Win32 programs, Centennial apps, and UWP apps. Making using PATH and EVs more straight forward.
• Allows UWP apps to read EV's at the user level without having to do a registry call.
• Allows UWP apps to read EV's at the machine scope without having to do a p/invoke.

Scope

| Capability | Priority |
| :---------- | :------- |
| At runtime, allow users to append and remove from PATH and PATHEXT. | Must |
| Include a system for tracking the PATH, PATHEXT, and EV changes and revert any changes when the app is uninstalled. | Must |
| At runtime, allow users to add their own EVs and track the changes. | Must |

Important Notes

• Restored EVs and PATH/PATHEXT will be determined by the last-write-time rule.
• API will not check to see if the appended PATH/PATHEXT value is valid.
• A PATH, PATHEXT, and EV change will be tracked via the API only when a packaged app is calling.
• RemoveFromPath[Ext] will only remove values written by the the app. It can not be used to remove any values from the path.
• To set EV's at the User scope the app needs to be fulltrust.
• To set EV's at the machine scope the app needs be running elevated.
• We won’t track changes that are made outside the API; and we won’t track uninstall of unpackaged apps.
• GetForUser will only support the current user in this iteration.

• Example in MIDL3
  //
  // Environment Variable WinRT API
  //

  namespace Windows.Process.Environment
  {
  
      [contract(Windows.Foundation.UniversalApiContract, 13)]
      runtimeclass EnvironmentManager
      {
  
          static EnvironmentManager GetForProcess();
          static EnvironmentManager GetForUser(User user);
          static EnvironmentManager GetForMachine();
  
          String GetEnvironmentVariable(String name);
          Windows.Foundation.Collections.IReadOnlyDictionaty<String, String> GetEnvironmentVariables();
  
          void SetEnvironmentVariable(
              String name,
              String value);
  
          void AppendToPath(String path);
          void RemoveFromPath(String path);
  
          void AppendToPathExt(String path);
          void RemoveFromPathExt(String path);
  }
  

Open Questions

• should the return value for GetEnviormentVariable be a nullable type?

[sylveon]

Why use those path APIs over an app execution alias?

[mdtauk]

Couldn't any changes be appended from an external source - so apps do not modify the OS setting directly?

Like Centennial apps having registry hives which get pulled in at app run? But entries can be cleanly removed or modified.

[Jaiganeshkumaran]

I think UWP apps should be let to change user environment variables only and not global ones

[dhoehna]

Why use those path APIs over an app execution alias?

Can you please explain more of what you mean by this question? An AppExecutionAlias is to run the app via the command line on win+r with an alias.

This API is also being considered for Win32 programs as well as packaged applications. The goal of this api is to have one location that everyone can use to manipulate PATH.

[sylveon]

App execution aliases remove the need to programmatically manipulate the PATH environment variable, and provide more control to the user (they can be disabled and enabled at will from the settings app).

[dhoehna]

Couldn't any changes be appended from an external source - so apps do not modify the OS setting directly?

Like Centennial apps having registry hives which get pulled in at app run? But entries can be cleanly removed or modified.

Correct. My app could use this API to append to the PATH and something outside of the API user, Win32 program, etc could modify the PATH. It could even delete the value the app added.

This API will track and revert any changes to any environment variable and PATH/PATHEXT when the app is uninstalled. Part of this API is to include a change tracker. The value that is restored will be the latest-written-value.

Here is an example.
Current Path A;B;C
My app add D. The path is now A;B;C;D.
User add E. The path is A;B;C;D;E.
My app is uninstalled. The path is now A;B;C;E.

Does that answer your question?

[dhoehna]

I think UWP apps should be let to change user environment variables only and not global ones

Hey @Jaiganeshkumaran,

That is correct. UWP apps won't be able to write to the global (Machine) scope because an app needs to be ran elevated in order to do so. Because UWP apps can't run elevated, they can't write to the global (machine) scope.

[BenJKuhn]

Path issues are a pain, much like managing IRQ levels, and hopefully one day they'll be a thing of the past. App Execution Aliases are the preferred mechanism for adding things to the path. There are other environment variables that various apps understand as well, and similarly as centrally managed singletons, they don't scale well.

Within your application, you can use the existing APIs SetEnvironmentVariable and GetEnvironmentVariable to control sub-processes. These APis are already supported in UWP applications and will also be covered by recently announced work to provide metadata and projection support for Win32 APIs: https://blogs.windows.com/windowsdeveloper/2021/01/21/making-win32-apis-more-accessible-to-more-languages/

However, there are no plans that I'm aware of to create new APIs that would control system-wide environment settings. This is a technology that, while still widely used, is gradually being replaced by more robust mechanisms. If there are other use cases that we should be looking at, please feel free to raise them.

Thanks,

Ben Kuhn

[dhoehna]

Hey @BenJKuhn,

There are other reasons for this API besides just PATH manipulation.

1. This API will allow for a clean uninstall of Environment Variables when an app that uses this API sets or modifies an Environment Variable. The same with PATH.
2. Because this is project reunion, it will be one singular API that UWP apps, Centennial apps, and Win32 programs can use to manipulate Environment Variables and PATH.
3. Allows for edits in the user and machine scope. (Since we don't have any native api's to set any Environment Variables in the user or machine scope)

[dhoehna]

App execution aliases remove the need to programmatically manipulate the PATH environment variable, and provide more control to the user (they can be disabled and enabled at will from the settings app).

I thought an App Execution Alias was for making your program callable from the command line and win+r. I don't think the App Execution Alias does not allow arbitrary edits to PATH.

This API does include more than PATH manipulation though. It also allows the tracking of the Environment Variable changes and allows a clean uninstall of them when the app is uninstalled.

[sylveon]

Any app execution alias an app creates is accessible from PATH. Most (if not all) edits to PATH by apps are to add their executables to it. Those usages can be replaced by app execution aliases.

[BenJKuhn]

I apparently closed this prematurely. There are folks looking into this. I'm re-opening this issue, accordingly.

[dhoehna]

@sylveon Very true. If most apps use the PATH for their own executable and will not use this API to set the PATH, that is okay. If the API review team decided to drop the PATH support, that is okay.

[dhoehna]

Appending to my earlier comment. This API is intended to work with Win32 programs as well and they will need to manipulate PATH. They don't have a manifest to use.

[Jaiganeshkumaran]

Appending to my earlier comment. This API is intended to work with Win32 programs as well and they will need to manipulate PATH. They don't have a manifest to use.

Hopefully, most desktop apps will become packaged. Unpackaged apps can use the existing flat API. Microsoft is making Win32 APIs available to other languages directly so there's no need for a new WinRT API for this old concept.

[dhoehna]

Unpackaged apps can use the existing flat API.

Very true. But the flat API's only works for the process. This would allow WIn32 programs, and Centennial packages to write to the User and machine scope as well.

EDIT: What other API's is Microsoft making? I'm not saying your wrong, I'm just not aware of them.