Skip to content

Commit 07e102d

Browse files
carlossanlopgewarren
carlossanlop
and
gewarren
authored
Document System.IO.FileSystemAclExtensions (#3684)
* Document System.IO.FileSystemAclExtensions * suggestions by gewarren Co-Authored-By: Genevieve Warren <[email protected]> * exception crefs Co-authored-by: Genevieve Warren <[email protected]>
1 parent 7afedf0 commit 07e102d

File tree

1 file changed

+83
-41
lines changed

1 file changed

+83
-41
lines changed

‎xml/System.IO/FileSystemAclExtensions.xml

Lines changed: 83 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
</Attribute>
2424
</Attributes>
2525
<Docs>
26-
<summary>To be added.</summary>
26+
<summary>Provides Windows-specific static extension methods for manipulating Access Control List (ACL) security attributes for files and directories.</summary>
2727
<remarks>To be added.</remarks>
2828
</Docs>
2929
<Members>
@@ -46,10 +46,22 @@
4646
<Parameter Name="directorySecurity" Type="System.Security.AccessControl.DirectorySecurity" Index="1" FrameworkAlternate="dotnet-plat-ext-3.1;netcore-3.1" />
4747
</Parameters>
4848
<Docs>
49-
<param name="directoryInfo">To be added.</param>
50-
<param name="directorySecurity">To be added.</param>
51-
<summary>To be added.</summary>
52-
<remarks>To be added.</remarks>
49+
<param name="directoryInfo">A directory that does not exist yet that will be created by the method.</param>
50+
<param name="directorySecurity">The access control and audit security for the directory.</param>
51+
<summary>Creates a new directory, ensuring it is created with the specified directory security. If the directory already exists, nothing is done.</summary>
52+
<remarks>
53+
<format type="text/markdown"><![CDATA[
54+
55+
## Remarks
56+
57+
This extension method was added to .NET Core to bring the functionality that was provided by the `System.IO.DirectoryInfo.Create(System.Security.AccessControl.DirectorySecurity)` .NET Framework method.
58+
59+
]]></format>
60+
</remarks>
61+
<exception cref="T:System.ArgumentNullException">
62+
<paramref name="directoryInfo" /> or <paramref name="directorySecurity" /> is <see langword="null" />.</exception>
63+
<exception cref="T:System.IO.DirectoryNotFoundException">Could not find a part of the path.</exception>
64+
<exception cref="T:System.UnauthorizedAccessException">Access to the path is denied.</exception>
5365
</Docs>
5466
</Member>
5567
<Member MemberName="Create">
@@ -76,16 +88,36 @@
7688
<Parameter Name="fileSecurity" Type="System.Security.AccessControl.FileSecurity" Index="6" FrameworkAlternate="dotnet-plat-ext-3.1;netcore-3.1" />
7789
</Parameters>
7890
<Docs>
79-
<param name="fileInfo">To be added.</param>
80-
<param name="mode">To be added.</param>
81-
<param name="rights">To be added.</param>
82-
<param name="share">To be added.</param>
83-
<param name="bufferSize">To be added.</param>
84-
<param name="options">To be added.</param>
85-
<param name="fileSecurity">To be added.</param>
86-
<summary>To be added.</summary>
87-
<returns>To be added.</returns>
88-
<remarks>To be added.</remarks>
91+
<param name="fileInfo">A file that does not exist yet that will be created by the method.</param>
92+
<param name="mode">One of the enumeration values that specifies how the operating system should open a file.</param>
93+
<param name="rights">One of the enumeration values that defines the access rights to use when creating access and audit rules.</param>
94+
<param name="share">One of the enumeration values for controlling the kind of access other file stream objects can have to the same file.</param>
95+
<param name="bufferSize">The number of bytes buffered for reads and writes to the file.</param>
96+
<param name="options">One of the enumeration values that describes how to create or overwrite the file.</param>
97+
<param name="fileSecurity">An object that determines the access control and audit security for the file.</param>
98+
<summary>Creates a new file stream, ensuring it is created with the specified properties and security settings.</summary>
99+
<returns>A file stream for the newly created file.</returns>
100+
<remarks>
101+
<format type="text/markdown"><![CDATA[
102+
103+
## Remarks
104+
105+
This extension method was added to .NET Core to bring the functionality that was provided by the `System.IO.FileStream.#ctor(System.String,System.IO.FileMode,System.Security.AccessControl.FileSystemRights,System.IO.FileShare,System.Int32,System.IO.FileOptions,System.Security.AccessControl.FileSecurity)` .NET Framework constructor.
106+
107+
]]></format>
108+
</remarks>
109+
<exception cref="T:System.ArgumentException">The <paramref name="rights" /> and <paramref name="mode" /> combination is invalid.</exception>
110+
<exception cref="T:System.ArgumentNullException">
111+
<paramref name="fileInfo" /> or <paramref name="fileSecurity" /> is <see langword="null" />.</exception>
112+
<exception cref="T:System.ArgumentOutOfRangeException">
113+
<paramref name="mode" /> or <paramref name="share" /> are out of their legal enum range.
114+
115+
-or-
116+
117+
<paramref name="bufferSize" /> is not a positive number.</exception>
118+
<exception cref="T:System.IO.DirectoryNotFoundException">Could not find a part of the path.</exception>
119+
<exception cref="T:System.IO.IOException">An I/O error occurred.</exception>
120+
<exception cref="T:System.UnauthorizedAccessException">Access to the path is denied.</exception>
89121
</Docs>
90122
</Member>
91123
<Member MemberName="GetAccessControl">
@@ -110,9 +142,9 @@
110142
<Parameter Name="directoryInfo" Type="System.IO.DirectoryInfo" RefType="this" />
111143
</Parameters>
112144
<Docs>
113-
<param name="directoryInfo">To be added.</param>
114-
<summary>To be added.</summary>
115-
<returns>To be added.</returns>
145+
<param name="directoryInfo">The existing directory from which to obtain the security information.</param>
146+
<summary>Returns the security information of a directory.</summary>
147+
<returns>The security descriptors of all the access control sections of the directory.</returns>
116148
<remarks>To be added.</remarks>
117149
</Docs>
118150
</Member>
@@ -138,9 +170,9 @@
138170
<Parameter Name="fileInfo" Type="System.IO.FileInfo" RefType="this" />
139171
</Parameters>
140172
<Docs>
141-
<param name="fileInfo">To be added.</param>
142-
<summary>To be added.</summary>
143-
<returns>To be added.</returns>
173+
<param name="fileInfo">The file from which to obtain the security information.</param>
174+
<summary>Returns the security information of a file.</summary>
175+
<returns>The security descriptors of all the access control sections of the file.</returns>
144176
<remarks>To be added.</remarks>
145177
</Docs>
146178
</Member>
@@ -166,10 +198,13 @@
166198
<Parameter Name="fileStream" Type="System.IO.FileStream" RefType="this" />
167199
</Parameters>
168200
<Docs>
169-
<param name="fileStream">To be added.</param>
170-
<summary>To be added.</summary>
171-
<returns>To be added.</returns>
201+
<param name="fileStream">An existing file from which to obtain the security information.</param>
202+
<summary>Returns the security information of a file.</summary>
203+
<returns>The security descriptors of all the access control sections of the file.</returns>
172204
<remarks>To be added.</remarks>
205+
<exception cref="T:System.ArgumentNullException">
206+
<paramref name="fileStream" /> is <see langword="null" />.</exception>
207+
<exception cref="T:System.ObjectDisposedException">The file stream is closed.</exception>
173208
</Docs>
174209
</Member>
175210
<Member MemberName="GetAccessControl">
@@ -195,10 +230,10 @@
195230
<Parameter Name="includeSections" Type="System.Security.AccessControl.AccessControlSections" />
196231
</Parameters>
197232
<Docs>
198-
<param name="directoryInfo">To be added.</param>
199-
<param name="includeSections">To be added.</param>
200-
<summary>To be added.</summary>
201-
<returns>To be added.</returns>
233+
<param name="directoryInfo">An existing directory from which to obtain the security information.</param>
234+
<param name="includeSections">The desired access control sections to retrieve.</param>
235+
<summary>Returns the security information of a directory.</summary>
236+
<returns>The security descriptors of the specified access control sections of the directory.</returns>
202237
<remarks>To be added.</remarks>
203238
</Docs>
204239
</Member>
@@ -225,10 +260,10 @@
225260
<Parameter Name="includeSections" Type="System.Security.AccessControl.AccessControlSections" />
226261
</Parameters>
227262
<Docs>
228-
<param name="fileInfo">To be added.</param>
229-
<param name="includeSections">To be added.</param>
230-
<summary>To be added.</summary>
231-
<returns>To be added.</returns>
263+
<param name="fileInfo">An existing file from which to obtain the security information.</param>
264+
<param name="includeSections">The desired access control sections to retrieve from the file.</param>
265+
<summary>Returns the security information of a file.</summary>
266+
<returns>The security descriptors of the specified access control sections of the file.</returns>
232267
<remarks>To be added.</remarks>
233268
</Docs>
234269
</Member>
@@ -255,10 +290,12 @@
255290
<Parameter Name="directorySecurity" Type="System.Security.AccessControl.DirectorySecurity" />
256291
</Parameters>
257292
<Docs>
258-
<param name="directoryInfo">To be added.</param>
259-
<param name="directorySecurity">To be added.</param>
260-
<summary>To be added.</summary>
293+
<param name="directoryInfo">An existing directory.</param>
294+
<param name="directorySecurity">The security information to apply to the directory.</param>
295+
<summary>Changes the security attributes of an existing directory.</summary>
261296
<remarks>To be added.</remarks>
297+
<exception cref="T:System.ArgumentNullException">
298+
<paramref name="directorySecurity" /> is <see langword="null" />.</exception>
262299
</Docs>
263300
</Member>
264301
<Member MemberName="SetAccessControl">
@@ -284,10 +321,12 @@
284321
<Parameter Name="fileSecurity" Type="System.Security.AccessControl.FileSecurity" />
285322
</Parameters>
286323
<Docs>
287-
<param name="fileInfo">To be added.</param>
288-
<param name="fileSecurity">To be added.</param>
289-
<summary>To be added.</summary>
324+
<param name="fileInfo">An existing file.</param>
325+
<param name="fileSecurity">The security information to apply to the file.</param>
326+
<summary>Changes the security attributes of an existing file.</summary>
290327
<remarks>To be added.</remarks>
328+
<exception cref="T:System.ArgumentNullException">
329+
<paramref name="fileSecurity" /> is <see langword="null" />.</exception>
291330
</Docs>
292331
</Member>
293332
<Member MemberName="SetAccessControl">
@@ -313,10 +352,13 @@
313352
<Parameter Name="fileSecurity" Type="System.Security.AccessControl.FileSecurity" />
314353
</Parameters>
315354
<Docs>
316-
<param name="fileStream">To be added.</param>
317-
<param name="fileSecurity">To be added.</param>
318-
<summary>To be added.</summary>
355+
<param name="fileStream">An existing file.</param>
356+
<param name="fileSecurity">The security information to apply to the file.</param>
357+
<summary>Changes the security attributes of an existing file.</summary>
319358
<remarks>To be added.</remarks>
359+
<exception cref="T:System.ArgumentNullException">
360+
<paramref name="fileStream" /> or <paramref name="fileSecurity" /> is <see langword="null" />.</exception>
361+
<exception cref="T:System.ObjectDisposedException">The file stream is closed.</exception>
320362
</Docs>
321363
</Member>
322364
</Members>

0 commit comments

Comments
 (0)