Skip to content

Commit 96de453

Browse files
wadepickettwadepickett
authored
Update sample readme for Create gRPC client & server (#18169)
1 parent b1ddc4d commit 96de453

File tree

1 file changed

+5
-183
lines changed

1 file changed

+5
-183
lines changed

‎aspnetcore/tutorials/grpc/readme.md

+5-183
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
page_type: sample
3-
description: "This tutorial shows how to create a gRPC Service and gRPC client on ASP.NET Core."
3+
description: "Sample projects for a gRPC Service and gRPC client on ASP.NET Core."
44
languages:
55
- csharp
66
products:
@@ -10,192 +10,14 @@ products:
1010
urlFragment: create-grpc-client
1111
---
1212

13-
# Create a gRPC client and server in ASP.NET Core 3.0 using Visual Studio
13+
# Create a gRPC client and server in ASP.NET Core 3.1
1414

15-
This tutorial shows how to create a .NET Core [gRPC](https://grpc.io/docs/guides/) client and an ASP.NET Core gRPC Server.
15+
This sample demonstrates a .NET Core [gRPC](https://grpc.io/docs/guides/) client and an ASP.NET Core gRPC Server.
1616

17-
At the end, you'll have a gRPC client that communicates with the gRPC Greeter service.
18-
19-
In this tutorial, you;
20-
21-
* Create a gRPC Server.
22-
* Create a gRPC client.
23-
* Test the gRPC client service with the gRPC Greeter service.
24-
25-
## Create a gRPC service
26-
27-
* From the Visual Studio **File** menu, select **New** > **Project**.
28-
* In the **Create a new project** dialog, select **ASP.NET Core Web Application**.
29-
* Select **Next**
30-
* Name the project **GrpcGreeter**. It's important to name the project *GrpcGreeter* so the namespaces will match when you copy and paste code.
31-
* Select **Create**
32-
* In the **Create a new ASP.NET Core Web Application** dialog:
33-
* Select **.NET Core** and **ASP.NET Core 3.0** in the dropdown menus.
34-
* Select the **gRPC Service** template.
35-
* Select **Create**
36-
37-
### Run the service
38-
39-
* Press `Ctrl+F5` to run the gRPC service without the debugger.
40-
41-
Visual Studio runs the service in a command prompt.
42-
43-
The logs show the service listening on `https://localhost:5001`.
44-
45-
```console
46-
info: Microsoft.Hosting.Lifetime[0]
47-
Now listening on: https://localhost:5001
48-
info: Microsoft.Hosting.Lifetime[0]
49-
Application started. Press Ctrl+C to shut down.
50-
info: Microsoft.Hosting.Lifetime[0]
51-
Hosting environment: Development
52-
info: Microsoft.Hosting.Lifetime[0]
53-
```
54-
55-
> [!NOTE]
56-
> The gRPC template is configured to use [Transport Layer Security (TLS)](https://tools.ietf.org/html/rfc5246). gRPC clients need to use HTTPS to call the server.
57-
>
58-
> macOS doesn't support ASP.NET Core gRPC with TLS. Additional configuration is required to successfully run gRPC services on macOS. For more information, see [gRPC and ASP.NET Core on macOS](xref:grpc/aspnetcore#grpc-and-aspnet-core-on-macos).
59-
60-
### Examine the project files
61-
62-
*GrpcGreeter* project files:
63-
64-
* *greet.proto*: The *Protos/greet.proto* file defines the `Greeter` gRPC and is used to generate the gRPC server assets. For more information, see [Introduction to gRPC](xref:grpc/index).
65-
* *Services* folder: Contains the implementation of the `Greeter` service.
66-
* *appSettings.json*: Contains configuration data, such as protocol used by Kestrel. For more information, see <xref:fundamentals/configuration/index>.
67-
* *Program.cs*: Contains the entry point for the gRPC service. For more information, see <xref:fundamentals/host/generic-host>.
68-
* *Startup.cs*: Contains code that configures app behavior. For more information, see [App startup](xref:fundamentals/startup).
69-
70-
## Create the gRPC client in a .NET console app
71-
72-
* Open a second instance of Visual Studio.
73-
* Select **File** > **New** > **Project** from the menu bar.
74-
* In the **Create a new project** dialog, select **Console App (.NET Core)**.
75-
* Select **Next**
76-
* In the **Name** text box, enter "GrpcGreeterClient".
77-
* Select **Create**.
78-
79-
### Add required packages
80-
81-
The gRPC client project requires the following packages:
82-
83-
* [Grpc.Net.Client](https://www.nuget.org/packages/Grpc.Net.Client), which contains the .NET Core client.
84-
* [Google.Protobuf](https://www.nuget.org/packages/Google.Protobuf/), which contains protobuf message APIs for C#.
85-
* [Grpc.Tools](https://www.nuget.org/packages/Grpc.Tools/), which contains C# tooling support for protobuf files. The tooling package isn't required at runtime, so the dependency is marked with `PrivateAssets="All"`.
86-
87-
Install the packages using either the Package Manager Console (PMC) or Manage NuGet Packages.
88-
89-
#### PMC option to install packages
90-
91-
* From Visual Studio, select **Tools** > **NuGet Package Manager** > **Package Manager Console**
92-
* From the **Package Manager Console** window, navigate to the directory in which the *GrpcGreeterClient.csproj* file exists.
93-
* Run the following commands:
94-
95-
```powershell
96-
Install-Package Grpc.Net.Client
97-
Install-Package Google.Protobuf
98-
Install-Package Grpc.Tools
99-
```
100-
101-
#### Manage NuGet Packages option to install packages
102-
103-
* Right-click the project in **Solution Explorer** > **Manage NuGet Packages**
104-
* Select the **Browse** tab.
105-
* Enter **Grpc.Net.Client** in the search box.
106-
* Select the **Grpc.Net.Client** package from the **Browse** tab and select **Install**.
107-
* Repeat for `Google.Protobuf` and `Grpc.Tools`.
108-
109-
### Add greet.proto
110-
111-
* Create a **Protos** folder in the gRPC client project.
112-
* Copy the **Protos\greet.proto** file from the gRPC Greeter service to the gRPC client project.
113-
* Edit the *GrpcGreeterClient.csproj* project file:
114-
115-
Right-click the project and select **Edit Project File**.
116-
117-
* Add an item group with a `<Protobuf>` element that refers to the **greet.proto** file:
118-
119-
```xml
120-
<ItemGroup>
121-
<Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
122-
</ItemGroup>
123-
```
124-
125-
### Create the Greeter client
126-
127-
Build the project to create the types in the `GrpcGreeter` namespace. The `GrpcGreeter` types are generated automatically by the build process.
128-
129-
Update the gRPC client *Program.cs* file with the following code:
130-
131-
```csharp
132-
using System;
133-
using System.Net.Http;
134-
using System.Threading.Tasks;
135-
using GrpcGreeter;
136-
using Grpc.Net.Client;
137-
138-
namespace GrpcGreeterClient
139-
{
140-
class Program
141-
{
142-
static async Task Main(string[] args)
143-
{
144-
// The port number(5001) must match the port of the gRPC server.
145-
var channel = GrpcChannel.ForAddress("https://localhost:5001");
146-
var client = new Greeter.GreeterClient(channel);
147-
var reply = await client.SayHelloAsync(
148-
new HelloRequest { Name = "GreeterClient" });
149-
Console.WriteLine("Greeting: " + reply.Message);
150-
Console.WriteLine("Press any key to exit...");
151-
Console.ReadKey();
152-
}
153-
}
154-
}
155-
```
156-
157-
*Program.cs* contains the entry point and logic for the gRPC client.
158-
159-
The Greeter client is created by:
160-
161-
* Instantiating a `GrpcChannel` containing the information for creating the connection to the gRPC service.
162-
* Using the `GrpcChannel` to construct the Greeter client.
163-
164-
## Test the gRPC client with the gRPC Greeter service
165-
166-
* In the Greeter service, press `Ctrl+F5` to start the server without the debugger.
167-
* In the `GrpcGreeterClient` project, press `Ctrl+F5` to start the client without the debugger.
168-
169-
The client sends a greeting to the service with a message containing its name "GreeterClient". The service sends the message "Hello GreeterClient" as a response. The "Hello GreeterClient" response is displayed in the command prompt:
170-
171-
```console
172-
Greeting: Hello GreeterClient
173-
Press any key to exit...
174-
```
175-
176-
The gRPC service records the details of the successful call in the logs written to the command prompt.
177-
178-
```console
179-
info: Microsoft.Hosting.Lifetime[0]
180-
Now listening on: https://localhost:5001
181-
info: Microsoft.Hosting.Lifetime[0]
182-
Application started. Press Ctrl+C to shut down.
183-
info: Microsoft.Hosting.Lifetime[0]
184-
Hosting environment: Development
185-
info: Microsoft.Hosting.Lifetime[0]
186-
Content root path: C:\GH\aspnet\docs\4\Docs\aspnetcore\tutorials\grpc\grpc-start\sample\GrpcGreeter
187-
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
188-
Request starting HTTP/2 POST https://localhost:5001/Greet.Greeter/SayHello application/grpc
189-
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
190-
Executing endpoint 'gRPC - /Greet.Greeter/SayHello'
191-
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
192-
Executed endpoint 'gRPC - /Greet.Greeter/SayHello'
193-
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
194-
Request finished in 78.32260000000001ms 200 application/grpc
195-
```
17+
For a tutorial on this sample see [Tutorial: Create a gRPC client and server in ASP.NET Core](https://docs.microsoft.com/aspnet/core/tutorials/grpc/grpc-start?view=aspnetcore-3.1&tabs=visual-studio)
19618

19719
### Docs help & next steps for gRPC
19820

19921
* [Introduction to gRPC on ASP.NET Core](https://docs.microsoft.com/aspnet/core/grpc/index?view=aspnetcore-3.0)
20022
* [gRPC services with C#](https://docs.microsoft.com/aspnet/core/grpc/basics?view=aspnetcore-3.0)
201-
* [Migrating gRPC services from C-core to ASP.NET Core](https://docs.microsoft.com/aspnet/core/grpc/migration?view=aspnetcore-3.0)
23+
* [Migrating gRPC services from C-core to ASP.NET Core](https://docs.microsoft.com/aspnet/core/grpc/migration?view=aspnetcore-3.0)

0 commit comments

Comments
 (0)