Skip to content

NegotiateStream - update documentation #4335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 17, 2020
Merged

NegotiateStream - update documentation #4335

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7c011ca
NegotiateStream - update documentation
Jun 4, 2020
f8c7642
format code
Jun 4, 2020
5526d18
Update xml/System.Net.Security/NegotiateStream.xml
aik-jahoda Jun 11, 2020
31398d5
Remove example
Jun 16, 2020
dcd500b
Merge branch 'jajahoda/NegotiateStream' of github.com:aik-jahoda/dotn…
Jun 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions samples/snippets/csharp/VS_Snippets_Remoting/NclNegoSyncClient/CS/client.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,10 @@ public static void Main(String[] args)
// Encode the test data into a byte array.
byte[] message = System.Text.Encoding.UTF8.GetBytes("Hello from the client.");
authStream.Write(message, 0, message.Length);
authStream.Flush();
authStream.Flush();
Console.WriteLine("Sent {0} bytes.", message.Length);
}
// Close the client connection.
}
// Close the client connection.
authStream.Close();
Console.WriteLine("Client closed.");
}
Expand Down
1 change: 1 addition & 0 deletions samples/snippets/csharp/VS_Snippets_Remoting/NclNegoasyncClient/CS/client.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ public static void Main(String[] args)

//</snippet3>
writeTask.Wait();
authStream.FlushAsync(default).Wait();
Console.WriteLine("Sent {0} bytes.", message.Length);
// Close the client connection.
authStream.Close();
Expand Down
22 changes: 18 additions & 4 deletions xml/System.Net.Security/NegotiateStream.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3073,10 +3073,24 @@ Authentication has not occurred.</exception>
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="net-5.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netstandard-2.1" />
</Parameters>
<Docs>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<summary>Causes any buffered data to be asynchronously written to the underlying device.</summary>
<returns>A task that represents the asynchronous flush operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method invokes <xref:System.IO.Stream.FlushAsync%2A> on the underlying stream.



## Examples
The following code example demonstrates flushing the stream.

[!code-csharp[NclNegoSyncClient#4](~/samples/snippets/csharp/VS_Snippets_Remoting/NclNegoasyncClient/CS/client.cs#4)]
Copy link
Contributor

@gewarren gewarren Jun 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code sample isn't rendering in the preview. Also, I don't see a snippet4 in the file:

https://github.com/dotnet/dotnet-api-docs/blob/f8c76428f485dbc09e9c4fa8b30877fc44ac10d8/samples/snippets/csharp/VS_Snippets_Remoting/NclNegoasyncClient/CS/client.cs

Copy link
Contributor Author

@aik-jahoda aik-jahoda Jun 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this section in the file is referred from multiple places. I will take a look if it renders correctly on other places too.

Copy link
Contributor Author

@aik-jahoda aik-jahoda Jun 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is quite inconsistency in the examples:
C++ and VB are same and uses BexinXXX, EndXXX methods
C# uses XXXAsync methods.

NclNegoasyncClient.cpp
client.cs
client.vb

It implies that in the BexinXXX method docs we show C# example however not for the specific api. On other side C++ and VB are accurate.

I'm not sure how to handle it as there is several options:

  1. Create BexinXXX, EndXXX variant for C# async methods
    1. it demonstrate legacy approach
    2. we still need Task based async examples - code duplication
  2. Let it like it is and remove C# example from BexinXXX, EndXXX
    1. It sounds strange to me as C# is main .net language and we would offer examples in other languages only
  3. Rework VB + C++ to not use BexinXXX, EndXXX but Task based async methods
    1. It would unify the examples
    2. it would require remove examples from BexinXXX, EndXXX docs and move it to Task based async methods

Example of mismatched examples:
https://docs.microsoft.com/en-us/dotnet/api/system.net.security.negotiatestream.beginwrite?view=netcore-3.1

The C# example doesn't contain the related api.

@karelz, any thought?

Copy link
Contributor Author

@aik-jahoda aik-jahoda Jun 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the example completely. There is follow up ticket: #4390


]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="ImpersonationLevel">
Expand Down