search

dotnet / dotnet-api-docs

.NET API reference documentation (.NET 5+, .NET Core, .NET Framework)
https://docs.microsoft.com/dotnet/api/
Other
704 stars 1.55k forks source link

Consider adding more examples for OperatingSystem #3336

Open carlossanlop opened 4 years ago

carlossanlop commented 4 years ago

MS Docs page: https://docs.microsoft.com/en-us/dotnet/api/system.operatingsystem?view=netcore-3.0 https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System/OperatingSystem.xml

The example only shows result examples for Windows 8.1 and 7. We should add an example for Windows 10 and a few non-Windows results, if supported (OSX, Ubuntu, etc.):

// If run on a Windows 8.1 system, the example displays output like the following:
//       Current OS Information:
//
//       Platform: Win32NT
//       Version String: Microsoft Windows NT 6.2.9200.0
//       Version Information:
//          Major: 6
//          Minor: 2
//       Service Pack: ''
// If run on a Windows 7 system, the example displays output like the following:
//       Current OS Information:
//
//       Platform: Win32NT
//       Version String: Microsoft Windows NT 6.1.7601 Service Pack 1
//       Version Information:
//          Major: 6
//          Minor: 1
//       Service Pack: 'Service Pack 1'

I don't recall if the code examples are stored in another repo or in dotnet-api-docs, so feel free to transfer the issue to another repo if necessary.

@mairaw

carlossanlop commented 4 years ago

I got this output for Windows 10 in my personal PC:

Current OS Information:

Platform: Win32NT
Version String: Microsoft Windows NT 6.2.9200.0
Version Information:
   Major: 6
   Minor: 2
Service Pack: ''
carlossanlop commented 4 years ago

I got this output in my Raspberry PI 3, running Raspbian:

Platform: Unix
Version String: Unix 4.19.66.7
Version Information:
   Major: 4
   Minor: 19
Service Pack: ''

In contrast, this is what I get when I run uname -a: Linux raspberrypi 4.19.66-v7+ #1253 SMP Thu Aug 15 11:49:46 BST 2019 armv7l GNU/Linux

Gnbrkm41 commented 4 years ago

Doesn't the windows example depend on whether the application has set the app manifest file to specifically target a specific OS? https://docs.microsoft.com/en-us/windows/win32/sysinfo/targeting-your-application-at-windows-8-1?redirectedfrom=MSDN

Running the snippet on the same PC, with .NET Framework/.NET Core on a blank Console project yields this result:

Current OS Information:

Platform: Win32NT
Version String: Microsoft Windows NT 6.2.9200.0
Version Information:
   Major: 6
   Minor: 2
Service Pack: ''

However, running the snippet on my PC, with LINQPad 6 yields this "correct" result:

Current OS Information:

Platform: Win32NT
Version String: Microsoft Windows NT 10.0.18999.0
Version Information:
   Major: 10
   Minor: 0
Service Pack: ''

Looking at the manifest file, LINQPad seems to be manifested to work with Win10, and therefore returns the "correct result":

 <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
                <application>
                        <!-- A list of all Windows versions that this application is designed to work with. Windows will automatically select the most compatible environment.-->

                        <!-- If your application is designed to work with Windows Vista, uncomment the following supportedOS node-->
                        <supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/>

                        <!-- If your application is designed to work with Windows 7, uncomment the following supportedOS node-->
                        <supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>

                        <!-- If your application is designed to work with Windows 8, uncomment the following supportedOS node-->
                        <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>

                        <!--Windows 8.1. http://stackoverflow.com/questions/17406850/how-can-we-check-if-the-current-os-is-win8-or-blue-->
                        <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>

                        <!--Windows 10-->
                        <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>

                </application>
        </compatibility>

IMO, I think it's worth briefly mentioning about this, and either emphasise on setting the app manifest, or suggest alternative ways to work around.

carlossanlop commented 4 years ago

@Gnbrkm41 I had no idea about this, so yes, we should definitely have this documented as well.

mairaw commented 4 years ago

Great idea @carlossanlop! Do you know a good person to talk about config? I've been wanting to discuss similar things and don't know where to start.

carlossanlop commented 4 years ago

I'm going to guess here... @tarekgh would you be a good contact for Maira to ask questions about System.OperatingSystem and config in general? If not, who could help?

tarekgh commented 4 years ago

I am not really the owner, but looking at the code I am seeing when calling Environment.OSVersion on Windows, we end up calling the native Windows API GetVersionExW and this API will just return whatever version of Windows the application built against. as @Gnbrkm41 mentioned it'll depend on the app manifest. GetVersionExW is well documented which you can refer to it for the behavior.

If want to get the real Windows version we are running on regardless of how the app built, can use RuntimeInformation.OSDescription