Example for setting PipeSecurity on named pipes doesn't work

[X-Celcius]

Description

The provided example does not compile / work. It says to do the following:

var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenNamedPipe("MyPipeName", listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;

        // Configure PipeSecurity
        listenOptions.UseNamedPipes(options =>
        {
            var pipeSecurity = new PipeSecurity();
            // Grant read/write access to the Users group
            pipeSecurity.AddAccessRule(new PipeAccessRule(
                "Users",
                PipeAccessRights.ReadWrite,
                AccessControlType.Allow));
            // Add additional rules as needed

            options.PipeSecurity = pipeSecurity;
        });
    });
});

However there are three issues I had:

1. You cannot call UseNamedPipes on listenOptions. This call needs to be made on the WebHost builder like this:

var builder = WebApplication.CreateBuilder(args);

// Configure PipeSecurity
builder.WebHost.UseNamedPipes(options =>
{
    var pipeSecurity = new PipeSecurity();
    // Grant read/write access to the Users group
    pipeSecurity.AddAccessRule(new PipeAccessRule(
        "Users",
        PipeAccessRights.ReadWrite,
        AccessControlType.Allow));
    // Add additional rules as needed

    options.PipeSecurity = pipeSecurity;
});
builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenNamedPipe("MyPipeName", listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
    });
});

2. Starting the server failed because it says the named pipe is already in use. This is actually misleading because it was caused by access being denied. I believe you need to also grant CreateNewInstance permission to the current user otherwise it is not allowed to create the named pipe.

    pipeSecurity.AddAccessRule(new PipeAccessRule(
        "Users",
        PipeAccessRights.ReadWrite | PipeAccessRights.CreateNewInstance,
        AccessControlType.Allow));

3. Setting PipeSecurity requires CurrentUserOnly to be set to false, otherwise you get an ArgumentException:
   System.ArgumentException: 'pipeSecurity' must be null when 'options' contains 'PipeOptions.CurrentUserOnly'. (Parameter 'pipeSecurity')

This may also be the reason why you need to grant CreateNewInstance rights, otherwise the current user has no permissions to do so.

The example should probably look like this (excluding usings, etc.):

var builder = WebApplication.CreateBuilder(args);

// Configure PipeSecurity
builder.WebHost.UseNamedPipes(options =>
{
    var pipeSecurity = new PipeSecurity();
    // Grant read/write access to the Users group
    pipeSecurity.AddAccessRule(new PipeAccessRule(
        "Users",
        PipeAccessRights.ReadWrite | PipeAccessRights.CreateNewInstance,
        AccessControlType.Allow));
    // Add additional rules as needed

    options.PipeSecurity = pipeSecurity;
    options.CurrentUserOnly = false;
});
builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenNamedPipe("MyPipeName", listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
    });
});

Page URL

https://learn.microsoft.com/en-us/aspnet/core/grpc/interprocess-namedpipes?view=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/grpc/interprocess-namedpipes.md

Document ID

58d486b8-0e04-9767-2089-deb43a28f56b

Platform Id

a2d799be-3207-916a-b50a-6cc65840d5b9

Article author

@JamesNK

Metadata

• ID: 58d486b8-0e04-9767-2089-deb43a28f56b
• PlatformId: a2d799be-3207-916a-b50a-6cc65840d5b9
• Service: aspnet-core
• Sub-service: grpc

Related Issues

[wadepickett]

Thanks @X-Celcius for the detailed issue and suggestions. Greatly appreciated.

@JamesNK for visibiltity

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-03-05
Issue: 36830
Model: GitHub Copilot

---

Issue Analysis: PipeSecurity code example for named pipes is incorrect and non-functional

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The code example in the "Configuring PipeSecurity for Named Pipes" section of the gRPC Named Pipes documentation does not compile and contains three distinct errors. The issue reporter has identified each problem and provided a corrected example that aligns with the actual ASP.NET Core API. This was verified by examining the ASP.NET Core source code at dotnet/aspnetcore, which confirms:

1. UseNamedPipes is an extension method on IWebHostBuilder, not on ListenOptions. The current example incorrectly calls listenOptions.UseNamedPipes(...).
2. PipeAccessRights.CreateNewInstance is required in addition to ReadWrite when setting custom PipeSecurity, otherwise pipe creation fails with a misleading "pipe already in use" error (actually access denied).
3. CurrentUserOnly must be set to false when providing a custom PipeSecurity object, otherwise an ArgumentException is thrown. This is confirmed by the test code in the product repo which uses both CurrentUserOnly = false and PipeAccessRights.CreateNewInstance.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/grpc/interprocess-namedpipes.md	51-91	"Configuring PipeSecurity for Named Pipes"

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential Documentation Updates

File: aspnetcore/grpc/interprocess-namedpipes.md
Location: Lines 57-84 (the code block inside "Configuring PipeSecurity for Named Pipes")
Type: Code example replacement

Current content (lines 57-84):

using Microsoft.AspNetCore.Server.Kestrel.Transport.NamedPipes;
using System.IO.Pipes;
using System.Security.AccessControl;

var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenNamedPipe("MyPipeName", listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;

        // Configure PipeSecurity
        listenOptions.UseNamedPipes(options =>
        {
            var pipeSecurity = new PipeSecurity();
            // Grant read/write access to the Users group
            pipeSecurity.AddAccessRule(new PipeAccessRule(
                "Users",
                PipeAccessRights.ReadWrite,
                AccessControlType.Allow));
            // Add additional rules as needed

            options.PipeSecurity = pipeSecurity;
        });
    });
});

Suggested direction:

using Microsoft.AspNetCore.Server.Kestrel.Transport.NamedPipes;
using System.IO.Pipes;
using System.Security.AccessControl;

var builder = WebApplication.CreateBuilder(args);

// Configure PipeSecurity
builder.WebHost.UseNamedPipes(options =>
{
    var pipeSecurity = new PipeSecurity();
    // Grant read/write access and CreateNewInstance to the Users group
    pipeSecurity.AddAccessRule(new PipeAccessRule(
        "Users",
        PipeAccessRights.ReadWrite | PipeAccessRights.CreateNewInstance,
        AccessControlType.Allow));
    // Add additional rules as needed

    options.PipeSecurity = pipeSecurity;
    options.CurrentUserOnly = false;
});
builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenNamedPipe("MyPipeName", listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
    });
});

File: aspnetcore/grpc/interprocess-namedpipes.md
Location: Lines 86-91 (the explanatory text following the code example)
Type: Update descriptive bullets

Current content (lines 86-91):

The preceding example:

* Uses `UseNamedPipes` to access and configure <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.NamedPipes.NamedPipeTransportOptions>.
* Sets the <xref:System.IO.Pipes.PipeSecurity> property to control which users or groups can connect to the named pipe.
* Grants read/write access to the `Users` group. Additional security rules can be added as needed for the scenario.

Suggested direction:

The preceding example:

* Calls `UseNamedPipes` on the <xref:Microsoft.AspNetCore.Hosting.IWebHostBuilder> to access and configure <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.NamedPipes.NamedPipeTransportOptions>.
* Sets <xref:Microsoft.AspNetCore.Server.Kestrel.Transport.NamedPipes.NamedPipeTransportOptions.CurrentUserOnly> to `false`, which is required when providing a custom <xref:System.IO.Pipes.PipeSecurity> object.
* Sets the <xref:System.IO.Pipes.PipeSecurity> property to control which users or groups can connect to the named pipe.
* Grants read/write and `CreateNewInstance` access to the `Users` group. The `CreateNewInstance` permission is needed to allow the server process to create the pipe. Additional security rules can be added as needed for the scenario.

> [!IMPORTANT]
> When setting a custom `PipeSecurity`, you must set `CurrentUserOnly = false`. Leaving `CurrentUserOnly` at its default value of `true` while also setting `PipeSecurity` throws an `ArgumentException`.

🎯 Suggested Action Plan

For documentation team review

1. Review and fix the code example: aspnetcore/grpc/interprocess-namedpipes.md

   • Navigate to: Lines 57-84
   • Section: "Configuring PipeSecurity for Named Pipes"
   • Fix 1: Move UseNamedPipes call from listenOptions to builder.WebHost
   • Fix 2: Add PipeAccessRights.CreateNewInstance to the access rule
   • Fix 3: Set options.CurrentUserOnly = false

2. Update explanatory text:

   • Navigate to: Lines 86-91
   • Update bullet points to explain CurrentUserOnly requirement and CreateNewInstance permission
   • Consider adding an [!IMPORTANT] block about the CurrentUserOnly/PipeSecurity incompatibility

3. Cross-reference with product source:

   • The ASP.NET Core test code already demonstrates the correct pattern with CurrentUserOnly = false and CreateNewInstance
   • The WebHostBuilderNamedPipeExtensions source confirms UseNamedPipes is only on IWebHostBuilder

⚠️ Review Considerations

• Verify change applies to .NET 8+ (the moniker range on this article is >= aspnetcore-8.0)
• The second example on the same page (lines 98-118, "Customize Kestrel named pipe endpoints") already correctly shows UseNamedPipes called on builder.WebHost, which is consistent with the suggested fix
• Consider whether the CreateNewInstance and CurrentUserOnly guidance should also be added to or referenced from the Kestrel endpoints documentation
• The article author is @JamesNK — they should be looped in for review

🔗 References

• Published article: https://learn.microsoft.com/en-us/aspnet/core/grpc/interprocess-namedpipes?view=aspnetcore-10.0
• Content source: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/grpc/interprocess-namedpipes.md
• ASP.NET Core UseNamedPipes source: https://github.com/dotnet/aspnetcore/blob/6dd7f70048be48975f8e9fd9b0331bd30002a059/src/Servers/Kestrel/Transport.NamedPipes/src/WebHostBuilderNamedPipeExtensions.cs
• ASP.NET Core test demonstrating correct pattern: https://github.com/dotnet/aspnetcore/blob/6dd7f70048be48975f8e9fd9b0331bd30002a059/src/Servers/Kestrel/Transport.NamedPipes/test/WebHostTests.cs#L199-L240
• Related issues: Search