The .NET runtime

The .NET runtime is the software stack responsible for installing your application code and dependencies, and then running that application in the flexible environment.

.NET version 6 and later are built using buildpacks, which requires you to choose an operating system in your app.yaml file. For example, to use .NET 8, you must specify Ubuntu 22 as the operating system.

For the full list of supported .NET versions, and their corresponding Ubuntu version, see the Runtime support schedule.

Choose a .NET version

New runtime versions

For .NET version 6 and later, you must include the runtime_config and operating_system settings in your app.yaml file to specify an operating system.

To use the new version, you must:

  • Update your project file.

    <Project Sdk="Microsoft.NET.Sdk.Web">
    
      <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
      </PropertyGroup>
    
      <ItemGroup>
        <None Update="app.yaml">
          <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
        </None>
      </ItemGroup>
    
    </Project>
    

    For more information see Migrate from ASP.NET Core 3.1 to 6.0.

  • Install gcloud CLI version 420.0.0 or later. You can update your CLI tooling by running the gcloud components update command. To view your installed version, you can run the gcloud version command.

  • Specify the operating_system setting in your app.yaml file:

      runtime: aspnetcore
      env: flex
    
      runtime_config:
          operating_system: "ubuntu22"
    

Optionally, you can specify a runtime version by including the runtime_version setting in your app.yaml file. By default, App Engine uses the latest available LTS .NET version if the runtime_version setting is not specified. For example, the app.yaml file looks as follows when specifying .NET8 on Ubuntu 22:

    runtime: aspnetcore
    env: flex

    runtime_config:
        runtime_version: "8"
        operating_system: "ubuntu22"

Previous runtime versions

To target a specific .NET SDK version, update your project file. For more information, see Migrate from ASP.NET Core 3.1 to 6.0.

If you want to use GKE or other Docker hosts, you need to create a Dockerfile that copies your application code and installs dependencies. For more information, see Custom Runtimes.

Deploy your App Engine app

To deploy your .NET app:

Run the following commands from the root directory where your app resides:

v6 and later

    gcloud app deploy

v3.1 and earlier

    dotnet restore
    dotnet publish -c Release
    gcloud app deploy

HTTPS and forwarding proxies

App Engine terminates the HTTPS connection at the load balancer and forwards the request to your application. Applications can examine the X-Forwarded-Proto to observe whether the original protocol was HTTP or HTTPS.

Some applications also need to ascertain the user's IP address. This is available in the standard X-Forwarded-For header.

Extending the runtime

The flexible environment .NET runtime can be used to create a custom runtime. Custom runtimes are configured via a Dockerfile.

You can customize the Dockerfile and .dockerignore as desired. Finally, you will need to specify runtime: custom instead of runtime: aspnetcore in app.yaml. See Customizing the .NET Runtime for more information.

Environment variables

The following environment variables are set by the runtime environment:

Environment variable Description
GAE_INSTANCE The name of the current instance.
GAE_MEMORY_MB The amount of memory available to the application process.
GAE_SERVICE The service name specified in your application's app.yaml file, or if no service name is specified, it is set to default.
GAE_VERSION The version label of the current application.
GOOGLE_CLOUD_PROJECT The Project ID associated with your application, which is visible in the Google Cloud console
PORT The port that will receive HTTP requests.

You can set additional configuration variables with appsettings.json.

Metadata server

Each instance of your application can use the Compute Engine metadata server to query information about the instance, including its host name, external IP address, instance ID, custom metadata, and service account information. App Engine does not allow you to set custom metadata for each instance, but you can set project-wide custom metadata and read it from your App Engine and Compute Engine instances.

This example function uses the metadata server to get the external IP address of the instance:

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Metadata-Flavor", new[] { "Google" });
response = await client.GetStringAsync(
    "http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip");