diff --git a/.github/policies/disallow-edits.yml b/.github/policies/disallow-edits.yml
index d66c667b5ff..ea3fe3fde49 100644
--- a/.github/policies/disallow-edits.yml
+++ b/.github/policies/disallow-edits.yml
@@ -19,6 +19,9 @@ configuration:
excludedFiles:
- xml/Microsoft.Extensions.FileSystemGlobbing/*
- xml/Microsoft.Extensions.FileSystemGlobbing.*/*
+ - filesMatchPattern:
+ matchAny: true
+ pattern: xml/System.CommandLine*/*
- filesMatchPattern:
matchAny: true
pattern: xml/System.Composition/*
diff --git a/README.md b/README.md
index 845641c5e70..b9400709646 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,9 @@ To contribute, see:
- The [.NET Contributor Guide :ledger:](https://learn.microsoft.com/contribute/dotnet/dotnet-contribute) for instructions on procedures we use.
- Issues labeled [`help wanted` :label:](https://github.com/dotnet/dotnet-api-docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+) for ideas.
+- The API reference docs for some assemblies are maintained in the assembly's source code outside this repo. For those assemblies, edits to the XML here are auto-generated and ported, so docs for APIs in those assemblies should be updated by editing the source code comments. For more information, see [here](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/adding-api-guidelines.md#documentation).
+
+ Namespaces and types whose docs are maintained in the assembly's source code repo set the [`open_to_public_contributors`](https://github.com/dotnet/dotnet-api-docs/blob/0ddbf94c587e7bdbbadc813a8b58fc4160a47b1f/docfx.json#L164) metadata to `false`. (That metadata disables the Edit button on the published docs.)
## :bookmark_tabs: Code of conduct
diff --git a/docfx.json b/docfx.json
index b96fdedd3c7..621d50787a5 100644
--- a/docfx.json
+++ b/docfx.json
@@ -147,6 +147,7 @@
"ms.topic": {
"api/Microsoft.Extensions**": "generated-reference",
"api/Microsoft.Extensions.FileSystemGlobbing**": "reference",
+ "api/System.CommandLine**": "generated-reference",
"api/System.Composition**": "generated-reference",
"api/System.Diagnostics.EventLog.Messages**": "generated-reference",
"api/System.Formats.Asn1**": "generated-reference",
@@ -163,18 +164,20 @@
},
"open_to_public_contributors": {
"api/Microsoft.Extensions**": false,
+ "api/System.CommandLine**": false,
"api/System.Composition**": false,
"api/System.Diagnostics.EventLog.Messages**": false,
"api/System.Formats.Asn1**": false,
"api/System.Formats.Cbor**": false,
"api/System.Formats.Nrbf**": false,
- "api/System.Linq.AsyncEnumerable.yml": false,
- "api/System.Linq.IOrderedAsyncEnumerable-1.yml": false,
"api/System.Net.ServerSentEvents**": false,
"api/System.Numerics.Tensors**": false,
+ "api/System.Runtime.Serialization.Schema**": false,
+
+ "api/System.Linq.AsyncEnumerable.yml": false,
+ "api/System.Linq.IOrderedAsyncEnumerable-1.yml": false,
"api/System.Runtime.Serialization.ISerializationCodeDomSurrogateProvider.yml": false,
"api/System.Runtime.Serialization.ImportOptions.yml": false,
- "api/System.Runtime.Serialization.Schema**": false,
"api/System.Runtime.Serialization.XsdDataContractExporter.yml": false
}
},
diff --git a/xml/System.Diagnostics.Tracing/EventSourceSettings.xml b/xml/System.Diagnostics.Tracing/EventSourceSettings.xml
index 4a78df08fae..5b2f4ec3dcf 100644
--- a/xml/System.Diagnostics.Tracing/EventSourceSettings.xml
+++ b/xml/System.Diagnostics.Tracing/EventSourceSettings.xml
@@ -137,7 +137,7 @@
4
- The ETW listener should use a manifest-based format when raising events. Setting this option is a directive to the ETW listener should use manifest-based format when raising events. This is the default option when defining a type derived from using one of the protected constructors.
+ The ETW listener should use a manifest-based format when raising events. This is the default option when defining a type derived from using one of the protected constructors. This format has lower per-event serialization overhead compared to . For more information, see Self-describing vs. manifest event formats.
@@ -177,7 +177,7 @@
8
- The ETW listener should use self-describing event format. This is the default option when creating a new instance of the using one of the public constructors.
+ The ETW listener should use self-describing event format. This is the default option when creating a new instance of the using one of the public constructors. This format has more capabilities and better compatibility with listeners that don't use the TraceEvent library, but has higher per-event serialization overhead compared to . For more information, see Self-describing vs. manifest event formats.
diff --git a/xml/System.Formats.Tar/TarFile.xml b/xml/System.Formats.Tar/TarFile.xml
index 78eee8f885b..7849eeac6ad 100644
--- a/xml/System.Formats.Tar/TarFile.xml
+++ b/xml/System.Formats.Tar/TarFile.xml
@@ -223,6 +223,7 @@
to overwrite files and directories in ; to avoid overwriting, and throw if any files or directories are found with existing names.
Extracts the contents of a stream that represents a tar archive into the specified directory.
+ If a symbolic link or junction in the tar archive results in a file being extracted outside the specified , an is thrown to ensure extraction remains within the same directory.
Files of type , , or can only be extracted in Unix platforms.
Elevation is required to extract a or to disk.
@@ -273,6 +274,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
to overwrite files and directories in ; to avoid overwriting, and throw if any files or directories are found with existing names.
Extracts the contents of a tar file into the specified directory.
+ If a symbolic link or junction in the tar archive results in a file being extracted outside the specified , an is thrown to ensure extraction remains within the same directory.
Files of type , , or can only be extracted in Unix platforms.
Elevation is required to extract a or to disk.
@@ -322,6 +324,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
Asynchronously extracts the contents of a stream that represents a tar archive into the specified directory.
A task that represents the asynchronous extraction operation.
+ If a symbolic link or junction in the tar archive results in a file being extracted outside the specified , an is thrown to ensure extraction remains within the same directory.
Files of type , , or can only be extracted in Unix platforms.
Elevation is required to extract a or to disk.
This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by .
@@ -376,6 +379,7 @@ Extracting one of the tar entries would have resulted in a file outside the spec
Asynchronously extracts the contents of a tar file into the specified directory.
A task that represents the asynchronous extraction operation.
+ If a symbolic link or junction in the tar archive results in a file being extracted outside the specified , an is thrown to ensure extraction remains within the same directory.
Files of type , , or can only be extracted in Unix platforms.
Elevation is required to extract a or to disk.
This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by .
diff --git a/xml/System.IO.Compression/ZipFile.xml b/xml/System.IO.Compression/ZipFile.xml
index 493bcc75a2e..a6063c04b99 100644
--- a/xml/System.IO.Compression/ZipFile.xml
+++ b/xml/System.IO.Compression/ZipFile.xml
@@ -1021,6 +1021,7 @@ An I/O error occurred while opening a file to be archived.
This method creates the specified directory and all subdirectories. The destination directory cannot already exist.
Exceptions related to validating the paths in the or the files in the zip archive contained in parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted.
Each extracted file has the same relative path to the directory specified by as its source entry has to the root of the archive.
+ If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.
is , contains only white space, or contains at least one invalid character.
@@ -1100,6 +1101,8 @@ An archive entry was compressed by using a compression method that isn't support
## Remarks
This method creates the specified directory and all subdirectories. The destination directory cannot already exist. Exceptions related to validating the paths in the `destinationDirectoryName` or `sourceArchiveFileName` parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted. Each extracted file has the same relative path to the directory specified by `destinationDirectoryName` as its source entry has to the root of the archive.
+ If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
+
## Examples
This example shows how to create and extract a zip archive by using the class. It compresses the contents of a folder into a zip archive and extracts that content to a new folder. To use the class, you must reference the `System.IO.Compression.FileSystem` assembly in your project.
@@ -1174,6 +1177,7 @@ An archive entry was compressed by using a compression method that isn't support
This method creates the specified directory and all subdirectories. The destination directory cannot already exist.
Exceptions related to validating the paths in the or the files in the zip archive contained in parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted.
Each extracted file has the same relative path to the directory specified by as its source entry has to the root of the archive.
+ If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.
is , contains only white space, or contains at least one invalid character.
@@ -1330,6 +1334,8 @@ Each entry will be extracted such that the extracted file has the same relative
The `sourceArchiveFileName` and `destinationDirectoryName` parameters accept both relative and absolute paths. A relative path is interpreted as relative to the current working directory.
+If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
+
If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.
]]>
@@ -1436,6 +1442,8 @@ A has been compressed usi
This method creates the specified directory and all subdirectories, if necessary. Exceptions related to validating the paths in the `destinationDirectoryName` or `sourceArchiveFileName` parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted. Each extracted file has the same relative path to the directory specified by `destinationDirectoryName` as its source entry has to the root of the archive.
+If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
+
If `entryNameEncoding` is set to a value other than `null`, entry names and comments are decoded according to the following rules:
- For entries where the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the entry names and comments are decoded by using the specified encoding.
@@ -1526,6 +1534,7 @@ If `entryNameEncoding` is set to `null`, entry names and comments are decoded ac
This method creates the specified directory and all subdirectories. The destination directory cannot already exist.
Exceptions related to validating the paths in the or the files in the zip archive contained in parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted.
Each extracted file has the same relative path to the directory specified by as its source entry has to the root of the archive.
+ If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.
is , contains only white space, or contains at least one invalid character.
@@ -1622,6 +1631,8 @@ An archive entry was compressed by using a compression method that isn't support
The `sourceArchiveFileName` and `destinationDirectoryName` parameters accept both relative and absolute paths. A relative path is interpreted as relative to the current working directory.
+ If an entry in the zip archive is a symbolic link, it's extracted as a regular folder since symbolic link information isn't preserved in the ZIP format.
+
If a file to be archived has an invalid last modified time, the first date and time representable in the zip timestamp format (midnight on January 1, 1980) will be used.
]]>
diff --git a/xml/System.Net.WebSockets/WebSocket.xml b/xml/System.Net.WebSockets/WebSocket.xml
index a0a0a1f179b..b8763993517 100644
--- a/xml/System.Net.WebSockets/WebSocket.xml
+++ b/xml/System.Net.WebSockets/WebSocket.xml
@@ -185,7 +185,7 @@ Exactly one send and one receive is supported on each Indicates the reason for closing the WebSocket connection.
Specifies a human readable explanation as to why the connection is closed.
The token that can be used to propagate notification that operations should be canceled.
- Closes the WebSocket connection as an asynchronous operation using the close handshake defined in the WebSocket protocol specification section 7.
+ Closes the WebSocket connection as an asynchronous operation using the close handshake defined in the WebSocket protocol specification, section 7.
The task object representing the asynchronous operation.
object will complete after the WebSocket has been closed.
- This method closes the WebSocket connection using the close handshake defined in the [WebSocket protocol specification](https://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-06) section 7.
+ This method closes the WebSocket connection using the close handshake defined in the [WebSocket protocol specification](https://datatracker.ietf.org/doc/html/rfc6455), section 7.
]]>
@@ -251,7 +251,7 @@ Exactly one send and one receive is supported on each Indicates the reason for closing the WebSocket connection.
Allows applications to specify a human readable explanation as to why the connection is closed.
The token that can be used to propagate notification that operations should be canceled.
- Initiates or completes the close handshake defined in the WebSocket protocol specification section 7.
+ Initiates or completes the close handshake defined in the WebSocket protocol specification, section 7.
The task object representing the asynchronous operation.