diff --git a/aspnetcore/grpc/test-tools.md b/aspnetcore/grpc/test-tools.md index dc9e44c9ed..1dbebc5afe 100644 --- a/aspnetcore/grpc/test-tools.md +++ b/aspnetcore/grpc/test-tools.md @@ -1,27 +1,29 @@ --- -title: Test gRPC services with gRPCurl in ASP.NET Core +title: Test gRPC services with Postman or gRPCurl in ASP.NET Core author: jamesnk -description: Learn how to test services with gRPC tools. gRPCurl a command-line tool for interacting with gRPC services. gRPCui is an interactive web UI. +description: Learn how to test services with gRPC tools. Postman is an interactive web UI. gRPCurl a command-line tool for interacting with gRPC services. gRPCui is an interactive web UI. monikerRange: '>= aspnetcore-3.0' ms.author: jamesnk ms.date: 03/31/2022 uid: grpc/test-tools --- -# Test gRPC services with gRPCurl in ASP.NET Core +# Test gRPC services with Postman or gRPCurl in ASP.NET Core By [James Newton-King](https://twitter.com/jamesnk) :::moniker range=">= aspnetcore-6.0" Tooling is available for gRPC that allows developers to test services without building client apps: -* [gRPCurl](https://github.com/fullstorydev/grpcurl) is a command-line tool that provides interaction with gRPC services. -* [gRPCui](https://github.com/fullstorydev/grpcui) builds on top of gRPCurl and adds an interactive web UI for gRPC, similar to tools such as Postman and Swagger UI. +* [Postman](https://www.postman.com/) is an API platform with an interactive UI for calling APIs. Postman can run in the browser or be downloaded and run locally. Postman supports calling gRPC services. +* [gRPCurl](https://github.com/fullstorydev/grpcurl) is an open-source command-line tool that provides interaction with gRPC services. +* [gRPCui](https://github.com/fullstorydev/grpcui) builds on top of gRPCurl and adds an open-source interactive web UI for gRPC. This article discusses how to: -* Set up gRPC reflection with a gRPC ASP.NET Core app. -* Download and install gRPCurl and gRPCui. -* Discover and test gRPC services with `grpcurl`. -* Interact with gRPC services via a browser using `grpcui`. +* Set up gRPC server reflection with a gRPC ASP.NET Core app. +* Interact with gRPC using test tools: + * Call gRPC services in Postman. + * Discover and test gRPC services with `grpcurl`. + * Interact with gRPC services via a browser using `grpcui`. > [!NOTE] > To learn how to unit test gRPC services, see . @@ -30,8 +32,8 @@ This article discusses how to: Tooling must know the Protobuf contract of services before it can call them. There are two ways to do this: -* Set up [gRPC reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) on the server. Tools, such as gRPCurl and Postman, automatically discover service contracts. -* Specify `.proto` files in command-line arguments to gRPCurl. +* Set up [gRPC reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) on the server. Tools, such as gRPCurl and Postman, use reflection to automatically discover service contracts. +* Add `.proto` files to the tool manually. It's easier to use gRPC reflection. gRPC reflection adds a new gRPC service to the app that clients can call to discover services. @@ -50,6 +52,25 @@ When gRPC reflection is set up: * Client apps that support gRPC reflection can call the reflection service to discover services hosted by the server. * gRPC services are still called from the client. Reflection only enables service discovery and doesn't bypass server-side security. Endpoints protected by [authentication and authorization](xref:grpc/authn-and-authz) require the caller to pass credentials for the endpoint to be called successfully. +## Postman + +Postman is an API platform. It supports calling gRPC services with an interactive UI, among its many features. + +To download and install Postman, see the [Download Postman page](https://www.postman.com/downloads/). + +### Use Postman + +Postman has an interactive UI for calling gRPC services. To call a gRPC service using Postman: + +1. Select the **New** button and choose **gRPC Request**. +2. Enter the gRPC server's hostname and port in the server URL. For example, `localhost:5000`. Don't include the `http` or `https` scheme in the URL. If the server uses [Transport Layer Security (TLS)](https://tools.ietf.org/html/rfc5246), select the padlock next to the server URL to enable TLS in Postman. +3. Navigate to the **Service definition** section, then select server reflection or import the app's proto file. When complete, the dropdown list next to the server URL textbox has a list of gRPC methods available. +4. To call a gRPC method, select it in the dropdown, select **Generate Example Message**, then select **Invoke** to send the gRPC call to the server. + +![gRPC in Postman](~/grpc/test-tools/static/postman.png) + +A short video is also available that [walks through using Postman with gRPC](https://youtu.be/gfYGqMb81GQ). + ## gRPCurl gRPCurl is a command-line tool created by the gRPC community. Its features include: @@ -155,6 +176,7 @@ The tool launches a browser window with the interactive web UI. gRPC services ar ## Additional resources +* [Postman homepage](https://www.postman.com/) * [gRPCurl GitHub homepage](https://github.com/fullstorydev/grpcurl) * [gRPCui GitHub homepage](https://github.com/fullstorydev/grpcui) * [`Grpc.AspNetCore.Server.Reflection`](https://www.nuget.org/packages/Grpc.AspNetCore.Server.Reflection) @@ -166,15 +188,17 @@ The tool launches a browser window with the interactive web UI. gRPC services ar :::moniker range=">= aspnetcore-3.0 < aspnetcore-6.0" Tooling is available for gRPC that allows developers to test services without building client apps: -* [gRPCurl](https://github.com/fullstorydev/grpcurl) is a command-line tool that provides interaction with gRPC services. -* [gRPCui](https://github.com/fullstorydev/grpcui) builds on top of gRPCurl and adds an interactive web UI for gRPC, similar to tools such as Postman and Swagger UI. +* [Postman](https://www.postman.com/) is an API platform with an interactive UI for calling APIs. Postman can run in the browser or be downloaded and run locally. Postman supports calling gRPC services. +* [gRPCurl](https://github.com/fullstorydev/grpcurl) is an open-source command-line tool that provides interaction with gRPC services. +* [gRPCui](https://github.com/fullstorydev/grpcui) builds on top of gRPCurl and adds an open-source interactive web UI for gRPC. This article discusses how to: -* Set up gRPC reflection with a gRPC ASP.NET Core app. -* Download and install gRPCurl and gRPCui. -* Discover and test gRPC services with `grpcurl`. -* Interact with gRPC services via a browser using `grpcui`. +* Set up gRPC server reflection with a gRPC ASP.NET Core app. +* Interact with gRPC using test tools: + * Call gRPC services in Postman. + * Discover and test gRPC services with `grpcurl`. + * Interact with gRPC services via a browser using `grpcui`. > [!NOTE] > To learn how to unit test gRPC services, see . @@ -183,8 +207,8 @@ This article discusses how to: Tooling must know the Protobuf contract of services before it can call them. There are two ways to do this: -* Set up [gRPC reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) on the server. Tools, such as gRPCurl and Postman, automatically discover service contracts. -* Specify `.proto` files in command-line arguments to gRPCurl. +* Set up [gRPC reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) on the server. Tools, such as gRPCurl and Postman, use reflection to automatically discover service contracts. +* Add `.proto` files to the tool manually. It's easier to use gRPC reflection. gRPC reflection adds a new gRPC service to the app that clients can call to discover services. @@ -203,6 +227,25 @@ When gRPC reflection is set up: * Client apps that support gRPC reflection can call the reflection service to discover services hosted by the server. * gRPC services are still called from the client. Reflection only enables service discovery and doesn't bypass server-side security. Endpoints protected by [authentication and authorization](xref:grpc/authn-and-authz) require the caller to pass credentials for the endpoint to be called successfully. +## Postman + +Postman is an API platform. It supports calling gRPC services with an interactive UI, among its many features. + +To download and install Postman, see the [Download Postman page](https://www.postman.com/downloads/). + +### Use Postman + +Postman has an interactive UI for calling gRPC services. To call a gRPC service using Postman: + +1. Select the **New** button and choose **gRPC Request**. +2. Enter the gRPC server's hostname and port in the server URL. For example, `localhost:5000`. Don't include the `http` or `https` scheme in the URL. If the server uses [Transport Layer Security (TLS)](https://tools.ietf.org/html/rfc5246), select the padlock next to the server URL to enable TLS in Postman. +3. Navigate to the **Service definition** section, then select server reflection or import the app's proto file. When complete, the dropdown list next to the server URL textbox has a list of gRPC methods available. +4. To call a gRPC method, select it in the dropdown, select **Generate Example Message**, then select **Invoke** to send the gRPC call to the server. + +![gRPC in Postman](~/grpc/test-tools/static/postman.png) + +A short video is also available that [walks through using Postman with gRPC](https://youtu.be/gfYGqMb81GQ). + ## gRPCurl gRPCurl is a command-line tool created by the gRPC community. Its features include: @@ -305,6 +348,7 @@ The tool launches a browser window with the interactive web UI. gRPC services ar ## Additional resources +* [Postman homepage](https://www.postman.com/) * [gRPCurl GitHub homepage](https://github.com/fullstorydev/grpcurl) * [gRPCui GitHub homepage](https://github.com/fullstorydev/grpcui) * [`Grpc.AspNetCore.Server.Reflection`](https://www.nuget.org/packages/Grpc.AspNetCore.Server.Reflection) diff --git a/aspnetcore/grpc/test-tools/static/postman.png b/aspnetcore/grpc/test-tools/static/postman.png new file mode 100644 index 0000000000..cf0982b598 Binary files /dev/null and b/aspnetcore/grpc/test-tools/static/postman.png differ diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index 5bd551babe..8c3d59b08a 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -869,7 +869,7 @@ items: uid: grpc/health-checks - name: Manage Protobuf references with dotnet-grpc uid: grpc/dotnet-grpc - - name: Test services with gRPCurl + - name: Test services with Postman and gRPCurl uid: grpc/test-tools - name: Migrate from C-core to gRPC for .NET uid: grpc/migration