Add note on xplat support for Encrypt/Decrypt on .NET Core #2259

SeanKilleen · 2019-04-05T02:47:15Z

Summary

Adds a brief explanation on cross-platform support in .NET Core to File.Encrypt and File.Decrypt.

While it seemed the documentation on support for using Encrypt/Decrypt was clear around requiring at least windows NT, NTFS drive etc. it was not as clear around cross-platform support within .NET Core. This explicitly calls that out, along with a brief explanation.

Fixes #964

SeanKilleen · 2019-04-05T04:09:31Z

It might make sense to use the [!NOTE] syntax here. If so, let me know and I'll adjust accordingly. 👍

rpetrusha · 2019-04-05T17:32:45Z

@JeremyKuhne, could you take a look at this PR, please?

rpetrusha

Thank you, @SeanKilleen, for contributing to the dotnet/dotnet-api-docs repo and enhancing the documentation for these two methods. I've suggested several changes. Also, I agree that a note would be the best format for presenting this information; it can be placed between the first and second paragraph of the Remarks section.

xml/System.IO/File.xml

JeremyKuhne

Looks good to me modulo @rpetrusha's comments

@rpetrusha

@rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <[email protected]>

@rpetrusha

@rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <[email protected]>

@rpetrusha

@rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <[email protected]>

@rpetrusha

@rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <[email protected]>

SeanKilleen · 2019-04-05T18:56:29Z

✅ Comments incorporated
✅ Changed the format to use [!NOTE] following conventions I saw elsewhere in the docs.

@rpetrusha I think this is ready to go assuming you agree with the implementation of the note style. 👍

rpetrusha · 2019-04-05T23:14:02Z

Thanks for making the changes, @SeanKilleen. We generally don't include headings in notes, though, since the note itself stands out clearly. I've suggested that you remove it, but also changed the note style to IMPORTANT to make it stand out a bit more.

SeanKilleen · 2019-04-06T00:56:27Z

@rpetrusha I originally copied the note styling from elsewhere in the docs so I assumed it was consistent, but maybe that's not the case -- no worries 👍

I think I've made the changes you requested (removed the bold formatting and replaced [!NOTE] with [!IMPORTANT] in both instances. Let me know if this isn't what you meant and I'll be happy to do whatever's needed to get it ready to go.

rpetrusha · 2019-04-08T16:50:57Z

Thanks for making these changes, @SeanKilleen. I think that two additional improvements to the note would be helpful:

Remove the text "A Note on .NET Core Cross-Platform Support". The note applies to both .NET Framework and .NET Core.
Add a blank line between "...situation"." and "Use of this API in .NET Core..." to make the .NET Core guidance stand out more clearly.

SeanKilleen · 2019-04-09T02:54:05Z

@rpetrusha I believe I've made the changes as you've requested. 👍 let me know if you have further feedback.

SeanKilleen · 2019-04-09T02:57:22Z

(FYI, given the build error, OpenPublishing.Build does not seem to have failed based on my changes alone as far as I can tell).

mairaw · 2019-04-09T07:32:37Z

No @SeanKilleen. Our engineering team deployed a fix to this issue today. I've kicked off a new build.

rpetrusha

Thanks for making these additional changes, @SeanKilleen. Your changes look good, and the build is now successful, so I'll merge your PR. The new content should be live on docs.microsoft.com in the next day or two.

rpetrusha · 2019-04-05T23:10:07Z

xml/System.IO/File.xml

-
+
+ > [!NOTE]
+ > **A Note on .NET Core Cross-Platform Support:** This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.


Suggested change

> **A Note on .NET Core Cross-Platform Support:** This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.

> This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.

rpetrusha · 2019-04-05T23:10:26Z

xml/System.IO/File.xml

-
+
+ > [!NOTE]
+ > **A Note on .NET Core Cross-Platform Support:** This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.


Suggested change

> **A Note on .NET Core Cross-Platform Support:** This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.

> This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.

rpetrusha · 2019-04-05T23:10:37Z

xml/System.IO/File.xml

 ## Remarks  
 The <xref:System.IO.File.Encrypt%2A> method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the <xref:System.IO.File.Decrypt%2A> method to decrypt a file encrypted by the <xref:System.IO.File.Encrypt%2A> method.  
-
+
+ > [!NOTE]


Suggested change

> [!NOTE]

> [!IMPORTANT]

rpetrusha · 2019-04-05T23:10:50Z

xml/System.IO/File.xml

@@ -1332,15 +1332,17 @@

 ## Remarks  
 The <xref:System.IO.File.Decrypt%2A> method allows you to decrypt a file that was encrypted using the <xref:System.IO.File.Encrypt%2A> method.  The <xref:System.IO.File.Decrypt%2A> method can decrypt only files that were encrypted using the current user account.  
-
+
+ > [!NOTE]


Suggested change

> [!NOTE]

> [!IMPORTANT]

Add note on xplat support for Encrypt/Decrypt on .NET Core

2be9a9f

SeanKilleen mentioned this pull request Apr 5, 2019

Hardly helpful #964

Closed

rpetrusha added the ✨ 1st-time dotnet-api-docs contributor! Indicates PRs from new contributors to the dotnet-api-docs repository label Apr 5, 2019

rpetrusha assigned SeanKilleen Apr 5, 2019

rpetrusha added this to the April 2019 milestone Apr 5, 2019

rpetrusha suggested changes Apr 5, 2019

View reviewed changes

xml/System.IO/File.xml Outdated Show resolved Hide resolved

xml/System.IO/File.xml Outdated Show resolved Hide resolved

xml/System.IO/File.xml Outdated Show resolved Hide resolved

xml/System.IO/File.xml Outdated Show resolved Hide resolved

JeremyKuhne approved these changes Apr 5, 2019

View reviewed changes

Ron Petrusha and others added 5 commits April 5, 2019 14:48

Update xml/System.IO/File.xml

a9f7113

@rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <[email protected]>

Update xml/System.IO/File.xml

fb6d1dc

@rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <[email protected]>

Update xml/System.IO/File.xml

d06b059

@rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <[email protected]>

Update xml/System.IO/File.xml

ab68f7e

@rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <[email protected]>

use note format instead

21e257b

update styling of note

a80f33c

Changes per feedback

b3593d5

mairaw closed this Apr 9, 2019

mairaw reopened this Apr 9, 2019

BillWagner added the changes-addressed Indicates PRs that had all comments addressed and are awaiting for new review label Apr 9, 2019

rpetrusha approved these changes Apr 9, 2019

View reviewed changes

rpetrusha merged commit c55b0f5 into dotnet:master Apr 9, 2019

mairaw removed the changes-addressed Indicates PRs that had all comments addressed and are awaiting for new review label Jun 4, 2019



		> [!NOTE]
		> A Note on .NET Core Cross-Platform Support: This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.

	> A Note on .NET Core Cross-Platform Support: This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.
	> This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.

Add note on xplat support for Encrypt/Decrypt on .NET Core #2259

Add note on xplat support for Encrypt/Decrypt on .NET Core #2259

Uh oh!

Conversation

SeanKilleen commented Apr 5, 2019

Summary

Uh oh!

SeanKilleen commented Apr 5, 2019

Uh oh!

rpetrusha commented Apr 5, 2019

Uh oh!

rpetrusha left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JeremyKuhne left a comment

Choose a reason for hiding this comment

Uh oh!

SeanKilleen commented Apr 5, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rpetrusha commented Apr 5, 2019

Uh oh!

SeanKilleen commented Apr 6, 2019

Uh oh!

rpetrusha commented Apr 8, 2019

Uh oh!

SeanKilleen commented Apr 9, 2019

Uh oh!

SeanKilleen commented Apr 9, 2019

Uh oh!

mairaw commented Apr 9, 2019

Uh oh!

rpetrusha left a comment

Choose a reason for hiding this comment

Uh oh!

rpetrusha Apr 5, 2019

Choose a reason for hiding this comment

Uh oh!

rpetrusha Apr 5, 2019

Choose a reason for hiding this comment

Uh oh!

rpetrusha Apr 5, 2019

Choose a reason for hiding this comment

Uh oh!

rpetrusha Apr 5, 2019

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SeanKilleen commented Apr 5, 2019 •

edited

Loading