Slice Tools for IceRPC

IceRpc.Slice.Tools allows you to compile Slice definitions (in .slice files) into C# code (in .cs files) within MSBuild projects.

This package includes:

• The Slice compiler, slicec, which parses and validates Slice files.
• The ZeroC.Slice.Generator, which generates C# code for Slice types (encoding, decoding, etc.).
• The IceRpc.Slice.Generator, which generates C# code for IceRPC-specific constructs (proxies, dispatchers, etc.).

The slicec compiler is a native tool with binaries for Linux (x64 and arm64), macOS (x64 and arm64) and Windows (x64). The C# generators are cross-platform .NET assemblies.

Once you've added the IceRpc.Slice.Tools NuGet package to your project, the Slice files of your project are automatically compiled into C# files every time you build this project.

When the Slice compiler compiles a Slice file and the resulting .cs file is identical to the existing output .cs file, the existing .cs file is kept as-is; the output file is overwritten only when something changed.

Source code | Package | Slice documentation

Slice files and Slice directories

The Slice compiler accepts two main inputs:

• the Slice files to compile into C# code (the Slice files)
• directories that contain reference Slice files (the Slice directories)

The Slice compiler parses the reference Slice files found in the Slice directories but does not generate code for them. They typically contain definitions referenced by the source Slice files.

The Slice files and Slice directories can overlap.

You select which files to include in your project's Slice files with the SliceFile item type. And you select which directory to include in your project's Slice directories with the SliceDirectory item type.

By default, all .slice files located in your project's home directory and any of its subdirectories, recursively, are included in SliceFile. You can prevent this auto-inclusion of .slice files by setting either EnableDefaultItems or EnableDefaultSliceFileItems to false. The default value of these properties is true.

You can also add Slice files to your project explicitly. For example:

<ItemGroup>
    <SliceFile Include="../Greeter.slice"/>
</ItemGroup>

This adds Greeter.slice to your project's Slice files even though this file is not in the project's home directory or any of its subdirectories.

Slice files must have a .slice extension.

The Slice directories are an aggregate of the SliceDirectory defined in your project (if any) and the SliceDirectory defined in NuGet packages referenced by your project.

For example, if your project's Slice files reference definitions in directory common/slice:

<ItemGroup>
    <SliceDirectory Include="$(MSBuildThisFileDirectory)../common/slice"/>
</ItemGroup>

Slice directory and NuGet package

As a general rule, when you package an assembly in a NuGet package and this assembly exports C# symbols generated by the Slice compiler, you should include the corresponding Slice files in your NuGet package. This allows consumers of your NuGet package to easily retrieve these Slice files.

You can also define SliceDirectory in this NuGet package so that any project that references this package automatically sees these Slice files when compiling.

For example, if you pack Slice files into the slice directory of your NuGet package, you want to include the following ItemGroup in the buildTransitive/<PackageName>.props you pack into this package:

<ItemGroup>
    <SliceDirectory Include="$(MSBuildThisFileDirectory)../slice"/>
</ItemGroup>

The ZeroC.Slice.Codec NuGet package follows this pattern and provides definitions for common Slice types such as WellKnownTypes::Duration, WellKnownTypes::TimeStamp and WellKnownTypes::Uri.

SliceFile item metadata

You can use the following SliceFile item metadata to customize the compilation and packaging of your Slice files. Each unique set of options results in a separate execution of the Slice compiler.

Name	Default	Description
AdditionalOptions		Specifies additional options to pass to the Slice compiler.
IceRpc	true	When true, the IceRpc.Slice.Generator runs in addition to the ZeroC.Slice.Generator, generating IceRPC-specific code (proxies, service interfaces). When false, only the ZeroC.Slice.Generator runs.
OutputDir	generated	Sets the output directory for the generated code.
Pack	false	Specifies whether or not to include the items (Slice files) in the NuGet package.
PackagePath	slice	Sets the target path in the NuGet package. Used only when Pack is true.

Generated code and NuGet packages

You need to reference the following NuGet packages to compile the generated C# code:

IceRpc metadata	NuGet package reference
true or no IceRpc metadata	IceRpc.Slice
false	ZeroC.Slice.Codec

Referencing IceRpc.Slice makes your project reference transitively ZeroC.Slice.Codec, IceRpc and System.IO.Pipelines.

Build telemetry

The IceRpc.Slice.Tools package collects anonymous build telemetry data about general usage. Participation in this program is optional, and you may opt out if you’d prefer not to share any information.

This package includes slicec-build-telemetry, a slicec plug-in that sends anonymous build telemetry data over a secure connection to the IceRPC build telemetry server during the compilation of Slice files.

This data includes:

• The versions of the slicec compiler and code generators.
• The system's operating system, version, and platform architecture.
• The .NET SDK version used by the build.
• Whether the build was executed in a continuous integration (CI) environment.
• The number of Slice interfaces, operations, and types in the compilation.

This data is used to help the IceRPC team understand how the tools are being used and to prioritize future development efforts. The data is stored in a private database and is not shared with any third parties.

To opt out of the build telemetry program, add the following property to your C# project file:

<PropertyGroup>
 <IceRpcBuildTelemetry>false</IceRpcBuildTelemetry>
</PropertyGroup>

Setting this property to false suppresses all build telemetry collection by removing the build telemetry plug-in from the compilation pipeline.