Upgrade Guide

C++ NuGet Package

The C++ NuGet package has been renamed to ZeroC.Ice.Cpp.

This package replaces the old zeroc.ice.vXXX packages from Ice 3.7.

It also includes the Slice tools for C++, so the zeroc.icebuilder.msbuild package is no longer required.

Upgrade Steps

Using the Visual Studio NuGet UI

1. Right-click your VC++ project → Manage NuGet Packages…

2. On the Installed tab, uninstall:

   • zeroc.icebuilder.msbuild
   • all zeroc.ice.vXXX packages

3. On the Browse tab, search for ZeroC.Ice.Cpp.

4. Select the desired 3.8 version and click Install.

5. Rebuild the solution.

C# NuGet Packages

The monolithic zeroc.ice.net package has been replaced with modular NuGet packages.

Upgrade Steps

Using the Visual Studio NuGet UI

1. Right-click your C# project → Manage NuGet Packages…

2. On the Installed tab, uninstall:

   • zeroc.icebuilder.msbuild
   • zeroc.ice.net

3. Install the required Ice 3.8 packages:

   • At minimum, install:

     • ZeroC.Ice.Slice.Tools
     • ZeroC.Ice

   • If your project depends on additional Ice services (e.g., Glacier2, IceGrid, IceStorm), install the corresponding package as listed in the package table above.

4. Select the desired 3.8 version and click Install.

5. Rebuild the solution.

Editing the Project File

The Ice 3.8 assemblies target .NET 8. Set the TargetFramework of your project to net8.0 or later, then replace the package references:

<PropertyGroup>
-  <TargetFramework>net6.0</TargetFramework>
+  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
  <SliceCompile Include="../slice/Greeter.ice" />
-  <PackageReference Include="zeroc.ice.net" Version="3.7.*" />
-  <PackageReference Include="zeroc.icebuilder.msbuild" Version="5.0.9" />
+  <PackageReference Include="ZeroC.Ice" Version="3.8.*" />
+  <PackageReference Include="ZeroC.Ice.Slice.Tools" Version="3.8.*" PrivateAssets="all" />
</ItemGroup>

Add a PackageReference for each service package your project uses, such as ZeroC.IceStorm.

iceboxnet, the IceBox server for .NET, is no longer an executable inside the zeroc.ice.net package: it is now a dotnet tool. Install it with:

dotnet tool install iceboxnet --create-manifest-if-needed

Slice Compilation

ZeroC.Ice.Slice.Tools replaces Ice Builder for MSBuild and compiles your Slice files the same way: it uses the same SliceCompile items, with the same OutputDir, IncludeDirectories and AdditionalOptions metadata and the same EnableDefaultSliceCompileItems property. Your existing SliceCompile items work unchanged. See the ZeroC.Ice.Slice.Tools package for details.

slice2cs no longer accepts the --tie, --impl, --impl-tie and --checksum options. See Using the Slice Compiler for the options of slice2cs in Ice 3.8.

Java Gradle Projects

The com.zeroc.slice-tools Gradle plugin replaces the com.zeroc.gradle.ice-builder.slice plugin used in Ice 3.7 Java Gradle projects. It includes the slice2java compiler for Linux, macOS, and Windows and the Ice Slice files.

The plugin adds a slice block to each Java or Android source set. In this block, srcDir or srcDirs sets the directories that hold your Slice files, includeSearchPath replaces the include setting of the Ice Builder plugin, and compilerArgs replaces args.

Before (3.7) ice-builder:

plugins {
  id "com.zeroc.gradle.ice-builder.slice" version "1.5.0"
}

slice {
    java {
        srcDir = '../slice'
        include = ["${projectDir}/../common/slice"]
    }
}

Now (3.8) slice-tools:

• New configuration using Kotlin DSL:

  Kotlin

  // build.gradle.kts
  
  plugins {
      // Apply the Slice-tools plugin to enable Slice compilation.
      id("com.zeroc.slice-tools") version "3.8.+"
  }
  
  sourceSets {
      main {
          slice {
              // Build all Slice files from the "../slice" subdirectory.
              srcDirs("../slice")
              // Search the "../common/slice" directory for included Slice files.
              includeSearchPath.from("../common/slice")
          }
      }
  }

• New configuration using Groovy DSL:

  Groovy

  // build.gradle
  
  plugins {
      // Apply the Slice-tools plugin to enable Slice compilation.
      id "com.zeroc.slice-tools" version "3.8.+"
  }
  
  sourceSets {
      main {
          slice {
              srcDirs "../slice"
              includeSearchPath.from("../common/slice")
          }
      }
  }

NPM Package

The Ice NPM package has been renamed and converted into a scoped package: @zeroc/ice. This new package also includes the slice2js compiler for Linux, macOS, and Windows.

Upgrade Steps

1. Uninstall the old packages:

   Shell

   npm uninstall ice slice2js

2. For preview builds, add the ZeroC NPM feed to your project’s .npmrc file:

   Properties

   # Use ZeroC nightly registry for @zeroc packages
   @zeroc:registry=https://download.zeroc.com/nexus/repository/npm-nightly/

3. Install the new package:

   Shell

   npm install @zeroc/ice --save

Python Static Code Generation

The Python static code generation has been improved in Ice 3.8 to follow a more typical Python package layout and to better support type hints.

The following changes may require updates to your projects:

• The slice2py options --all and --prefix have been removed.
• The slice2py option --build replaces the --no-package and --build-package options.
• slice2py replaces the package index files (__init__.py) each time it generates them.
• The python:package and python:pkgdir metadata directives have been removed.
• The name and location of Python generated files has changed.

Upgrade Steps

Replacing --all

If you were using --all to automatically compile included Slice files, you must now list all required files explicitly.

Before (3.7):

slice2py --all Root.ice

Now (3.8):

slice2py Foo.ice Bar.ice Root.ice

Here Foo.ice and Bar.ice represent all files included by Root.ice.

Replacing --prefix

If you used --prefix to control the prefix of generated file names, remove it.

Instead:

• Use the default mapping for generated modules, and
• Apply the new python:identifier metadata when you need to remap a generated name (e.g., to avoid a collision with a Python builtin or standard library module).

Replacing python:package

If you used the python:package metadata directive to control the package of a generated module, remove it.

Instead, use python:identifier metadata, which works consistently with all Slice constructs (modules, classes, enums, etc.), not just modules.

-["python:package:zeroc"]
+["python:identifier:zeroc.sys"]
 module sys
 {
     interface Process
     {
         // ...
     }
 }

New File Layout

The Python mapping now generates a Python module for each Slice-defined type, placing it inside a package that corresponds to the Slice module.

module VisitorCenter
{
    interface Greeter
    {
        string greet(string name);
    }
}

Generated output (3.7):

./VisitorCenter/__init__.py
./Greeter_ice.py

Generated output (3.8):

./VisitorCenter/__init__.py
./VisitorCenter/Greeter_forward.py
./VisitorCenter/Greeter.py

Key points:

• Generated files no longer use the _ice suffix.

• All generated files are placed inside the corresponding package directory.

• For Slice classes and interfaces, an additional <name>_forward.py file is generated for forward declarations.

  Applications do not need to import these _forward modules directly.

Package Index Files

The package index file (__init__.py) that slice2py generates for a package exports the definitions of the Slice files passed to that slice2py command. The Ice 3.7 compiler added the Slice file it compiled to the existing index file, so a build could compile the Slice files of a module one at a time. The Ice 3.8 compiler replaces the index file each time it generates it.

For example, when Clock.ice and Alarm.ice both define types in the Slice module EarlyRiser, the second command below leaves generated/EarlyRiser/__init__.py with only the definitions of Alarm.ice:

slice2py --output-dir generated Clock.ice
slice2py --output-dir generated Alarm.ice

Compile all the Slice files that contribute to a package with one command:

slice2py --output-dir generated Clock.ice Alarm.ice

If your build compiles each Slice file with a separate command, generate only the modules with these commands, then generate the index files with a command that lists all the Slice files:

slice2py --output-dir generated --build=modules Clock.ice
slice2py --output-dir generated --build=modules Alarm.ice
slice2py --output-dir generated --build=index Clock.ice Alarm.ice

Replacing --no-package and --build-package

The --build option replaces the --no-package and --build-package options. It accepts modules, index or all; all, the default, generates the modules and the package index files. See Using the Slice Compiler.

Tracking Generated Files

The Ice 3.7 compiler generated one file per Slice file, <name>_ice.py, plus the package index files. To get the files that the Ice 3.8 compiler generates from a set of Slice files, run slice2py with the --list-generated option and the value modules, index or all:

slice2py --output-dir generated --list-generated=all Clock.ice Alarm.ice

With this option, slice2py generates no file. It prints the path of each file, relative to the output directory, on a separate line.

Package Imports

In Ice 3.7, Python generated packages would automatically export nested sub-packages.

This is no longer the case in Ice 3.8: you must explicitly import nested packages.

Ice 3.7:

import Foo

# Nested subpackage is automatically available
c = Foo.Nested.Color.Red

Ice 3.8:

from Foo import Nested

c = Nested.Color.Red

Or import only what you need:

from Foo.Nested import Color

c = Color.Red

Swift Package

ZeroC distributes Ice for Swift as the Swift package https://github.com/zeroc-ice/ice.git. This package replaces the Carthage dependency and the ice-spm Swift package of Ice 3.7.

The package includes the slice2swift compiler, which the CompileSlice plugin runs during Swift Package Manager and Xcode builds.

Upgrade Steps

1. Remove Ice from the Carthage dependencies of your project, or remove the ice-spm package from Package.swift.

2. Add the ice package to Package.swift, and add the products you need to the dependencies of each target. The package requires macOS 15 or later, or iOS 18 or later, and Swift 6.1 or later: set the swift-tools-version of Package.swift to 6.1.

   Diff

   -// swift-tools-version: 5.5
   +// swift-tools-version: 6.1
   
    import PackageDescription
   
    let package = Package(
        name: "greeter",
   +    platforms: [.macOS(.v15)],
        dependencies: [
   -        .package(url: "https://github.com/zeroc-ice/ice-spm.git", from: "3.7.11"),
   -        .package(url: "https://github.com/mxcl/PromiseKit.git", from: "6.22.1"),
   +        .package(url: "https://github.com/zeroc-ice/ice.git", .upToNextMinor(from: "3.8.3"))
        ],
        targets: [
            .executableTarget(
                name: "Server",
   -            dependencies: [.product(name: "Ice", package: "ice-spm"), "PromiseKit"]
   +            dependencies: [.product(name: "Ice", package: "ice")],
   +            plugins: [.plugin(name: "CompileSlice", package: "ice")]
            )
        ]
    )

3. Add the CompileSlice plugin to each target that compiles Slice files, as shown above. The plugin compiles the .ice files among the source files of the target. To compile Slice files stored elsewhere, add a slice-plugin.json file to the source files of the target. Paths in this file are relative to its directory.

   json

   {
     "sources": ["../../slice/Greeter.ice"]
   }

   Key	Description
   sources	The Slice files that the plugin compiles. A directory stands for the .ice files directly in it.
   search_paths	The directories that slice2swift searches for included Slice files (-I options).

   The plugin adds the Slice files of Ice to the search path.

C++ Mapping

Ice 3.7 provided two C++ mappings: the C++98 mapping and the C++11 mapping. Ice 3.8 provides a single C++ mapping, derived from the C++11 mapping of Ice 3.7. It requires a C++17 compiler.

This section has two parts: one for an application that uses the C++11 mapping of Ice 3.7, and one for an application that uses the C++98 mapping.

If your application uses the C++98 mapping, port it directly to the Ice 3.8 mapping: there is nothing to gain from porting it to the C++11 mapping first. A proxy, for example, is a GreeterPrx value in both the C++98 mapping and the Ice 3.8 mapping, while the C++11 mapping holds it in a std::shared_ptr<GreeterPrx>.

Upgrading from the C++11 Mapping

An application that uses the C++11 mapping of Ice 3.7 no longer defines ICE_CPP11_MAPPING, and links with libraries whose names have no ++11 suffix: Ice replaces Ice++11.

Proxies

In Ice 3.7, the C++11 mapping holds every proxy in a std::shared_ptr<GreeterPrx>. In Ice 3.8, a generated proxy class such as GreeterPrx is a concrete class with value semantics, and a proxy that can be null is a std::optional<GreeterPrx>. The Slice compiler maps a proxy parameter, return value or field to std::optional<GreeterPrx>.

Update the variables, data members, containers and servant operation signatures that hold a proxy, and replace nullptr with std::nullopt:

-std::shared_ptr<GreeterPrx> greeter = nullptr;
+std::optional<GreeterPrx> greeter = std::nullopt;

-void initiateCallback(std::shared_ptr<CallbackReceiverPrx> receiver, const Ice::Current& current) override;
+void initiateCallback(std::optional<CallbackReceiverPrx> receiver, const Ice::Current& current) override;

Both GreeterPrx and std::optional<GreeterPrx> provide operator->, so an invocation written as greeter->greet("alice") compiles unchanged.

The functions that create a proxy, such as Communicator::propertyToProxy, ObjectAdapter::add and Connection::createProxy, are now function templates: you choose the type of the proxy they return. The default is Ice::ObjectPrx; we recommend that you always specify the proxy type. For example:

// widget is a std::optional<WidgetPrx>
auto widget = communicator->propertyToProxy<WidgetPrx>("MyWidget");

Optional Values

std::optional replaces Ice::optional and IceUtil::Optional; std::nullopt replaces Ice::nullopt and IceUtil::None.

-Ice::optional<std::string> opString(Ice::optional<std::string> p1, Ice::optional<std::string>& p2,
-                                    const Ice::Current& current) override;
+std::optional<std::string> opString(std::optional<std::string> p1, std::optional<std::string>& p2,
+                                    const Ice::Current& current) override;

Integer Types

The Slice compiler now maps the Slice integer types to the fixed-width integer types of the C++ standard library, and the Ice::Byte, Ice::Short, Ice::Int, Ice::Long, Ice::Float and Ice::Double aliases no longer exist.

Update the servant operation signatures and the variables that use these types. A Slice sequence<byte> now maps to std::vector<std::byte>; in Ice 3.7, it mapped to std::vector<Ice::Byte>. std::int64_t and long long are distinct types on some platforms, such as 64-bit Linux where std::int64_t is long; there, a servant function declared with a long long parameter no longer overrides the generated function, and a std::vector<long long> is not a Slice sequence<long>.

-long long int opLong(long long int p1, long long int& p2, const Ice::Current& current) override;
+std::int64_t opLong(std::int64_t p1, std::int64_t& p2, const Ice::Current& current) override;

IceUtil

The IceUtil namespace and the IceUtil headers no longer exist:

• Ice::CtrlCHandler replaces IceUtil::CtrlCHandler.
• The string converter API, such as StringConverter and setProcessStringConverter, is now in the Ice namespace.
• The other IceUtil classes, such as IceUtil::Mutex, IceUtil::Thread and IceUtil::Time, have been removed: use the C++ standard library.

Plug-in Registration

Ice::registerPluginFactory and the Ice::registerXxx functions of Ice/RegisterPlugins.h have been removed. In Ice 3.8, you install a plug-in by adding its factory to the pluginFactories field of the InitializationData you pass to Ice::initialize:

-Ice::registerIceDiscovery();
-auto communicator = Ice::initialize(argc, argv);
+Ice::InitializationData initData;
+initData.properties = Ice::createProperties(argc, argv);
+initData.pluginFactories = {IceDiscovery::discoveryPluginFactory()};
+auto communicator = Ice::initialize(initData);

• Ice::registerIceDiscovery, Ice::registerIceLocatorDiscovery, Ice::registerIceBT and Ice::registerIceIAP become IceDiscovery::discoveryPluginFactory(), IceLocatorDiscovery::locatorDiscoveryPluginFactory(), IceBT::btPluginFactory() and Ice::iapPluginFactory() in pluginFactories.
• Ice::registerIceSSL, Ice::registerIceUDP and Ice::registerIceWS go away: the Ice library includes the SSL, UDP and WebSocket transports. When you link with the static Ice library, add Ice::udpPluginFactory() and Ice::wsPluginFactory() to pluginFactories for the UDP and WebSocket transports.

The string converter plug-in, installed with Ice::registerIceStringConverter or an Ice.Plugin property, has been removed. See String Converters for the string converters of Ice 3.8.

See Plug-in API for more information.

Upgrading from the C++98 Mapping

Proxies

A proxy remains a GreeterPrx value. In the C++98 mapping, a null proxy is written 0; in Ice 3.8, a proxy that can be null is a std::optional<GreeterPrx>, and std::nullopt replaces 0. The Slice compiler maps a proxy parameter, return value or field to std::optional<GreeterPrx>.

-GreeterPrx greeter = 0;
+std::optional<GreeterPrx> greeter = std::nullopt;

Ice::checkedCast and Ice::uncheckedCast replace the static checkedCast and uncheckedCast functions of the proxy classes, and Ice::checkedCast returns a std::optional:

-GreeterPrx greeter = GreeterPrx::checkedCast(base);
+std::optional<GreeterPrx> greeter = Ice::checkedCast<GreeterPrx>(base);

The functions that create a proxy, such as Communicator::propertyToProxy, ObjectAdapter::add and Connection::createProxy, are now function templates: you choose the type of the proxy they return. The default is Ice::ObjectPrx; we recommend that you always specify the proxy type. For example:

// widget is a std::optional<WidgetPrx>
auto widget = communicator->propertyToProxy<WidgetPrx>("MyWidget");

Servants and Class Instances

GreeterPtr, Ice::ObjectPtr and the other Ptr types are now aliases for std::shared_ptr, such as std::shared_ptr<Greeter>. Create servants and class instances with std::make_shared, and replace the dynamicCast function of these types with std::dynamic_pointer_cast:

-GreeterPtr servant = new GreeterI;
+GreeterPtr servant = std::make_shared<GreeterI>();

-MyClassPtr instance = MyClassPtr::dynamicCast(value);
+MyClassPtr instance = std::dynamic_pointer_cast<MyClass>(value);

A servant function receives its in-parameters by value, where the C++98 mapping passes them by const reference:

-virtual std::string greet(const std::string& name, const Ice::Current& current);
+std::string greet(std::string name, const Ice::Current& current) override;

Asynchronous Invocations

The begin_ and end_ functions and their callback objects no longer exist. Call the Async function of the operation instead: it returns a std::future, or accepts response, exception and sent callback functions.

-Ice::AsyncResultPtr result = greeter->begin_greet("alice");
-std::string greeting = greeter->end_greet(result);
+std::future<std::string> future = greeter->greetAsync("alice");
+std::string greeting = future.get();

Asynchronous Dispatch

For an operation with the amd metadata, the servant implements an Async function in place of the _async function, and the AMD_ callback object becomes two functions: response, which replaces ice_response, and exception, which replaces ice_exception.

-virtual void greet_async(const AMD_Greeter_greetPtr& cb, const std::string& name, const Ice::Current& current);
+void greetAsync(std::string name, std::function<void(std::string_view)> response,
+                std::function<void(std::exception_ptr)> exception, const Ice::Current& current) override;

The Slice compiler also generates an asynchronous skeleton class, such as AsyncGreeter, in which every operation is dispatched this way, without the amd metadata.

Optional Values

std::optional replaces IceUtil::Optional, and std::nullopt replaces IceUtil::None.

Integer Types

The Slice compiler now maps the Slice integer types to the fixed-width integer types of the C++ standard library, and the Ice::Byte, Ice::Short, Ice::Int, Ice::Long, Ice::Float and Ice::Double aliases no longer exist.

Update the servant operation signatures and the variables that use these types. A Slice sequence<byte> now maps to std::vector<std::byte>; in Ice 3.7, it mapped to std::vector<Ice::Byte>.

IceUtil

The IceUtil namespace and the IceUtil headers no longer exist:

• Ice::CtrlCHandler replaces IceUtil::CtrlCHandler.
• The string converter API, such as StringConverter and setProcessStringConverter, is now in the Ice namespace.
• std::shared_ptr replaces IceUtil::Handle: a class held in a std::shared_ptr doesn't derive from IceUtil::Shared.
• The other IceUtil classes, such as IceUtil::Mutex, IceUtil::Thread and IceUtil::Time, have been removed: use the C++ standard library.

Plug-in Registration

Ice::registerPluginFactory and the Ice::registerXxx functions of Ice/RegisterPlugins.h have been removed. In Ice 3.8, you install a plug-in by adding its factory to the pluginFactories field of the InitializationData you pass to Ice::initialize:

-Ice::registerIceDiscovery();
-Ice::CommunicatorPtr communicator = Ice::initialize(argc, argv);
+Ice::InitializationData initData;
+initData.properties = Ice::createProperties(argc, argv);
+initData.pluginFactories = {IceDiscovery::discoveryPluginFactory()};
+Ice::CommunicatorPtr communicator = Ice::initialize(initData);

• Ice::registerIceDiscovery, Ice::registerIceLocatorDiscovery, Ice::registerIceBT and Ice::registerIceIAP become IceDiscovery::discoveryPluginFactory(), IceLocatorDiscovery::locatorDiscoveryPluginFactory(), IceBT::btPluginFactory() and Ice::iapPluginFactory() in pluginFactories.
• Ice::registerIceSSL, Ice::registerIceUDP and Ice::registerIceWS go away: the Ice library includes the SSL, UDP and WebSocket transports. When you link with the static Ice library, add Ice::udpPluginFactory() and Ice::wsPluginFactory() to pluginFactories for the UDP and WebSocket transports.

The string converter plug-in, installed with Ice::registerIceStringConverter or an Ice.Plugin property, has been removed. See String Converters for the string converters of Ice 3.8.

See Plug-in API for more information.

Optional Values

The Ice C# API and the code generated by slice2cs are now #nullable enable, and Ice uses the standard ? notation for all nullable types: a proxy that can be null is a GreeterPrx?, a class instance that can be null is a Person?, and so on. We recommend enabling nullable reference types in your own project (<Nullable>enable</Nullable>), so that the compiler checks your use of these types.

The Ice.Optional<T> struct and Ice.Util.None have been removed. An optional field or parameter now maps to a nullable type, where null means "not set". See Fields.

-public override void setAge(Ice.Optional<int> age, Ice.Current current)
+public override void setAge(int? age, Ice.Current current)
{
-    if (age.HasValue)
+    if (age is int value)
    {
-        _age = age.Value;
+        _age = value;
    }
}

-person.nickname = Ice.Util.None;
+person.nickname = null;

Structures

A Slice struct now maps to a C# record struct or to a sealed record class, depending on the types of its fields. See Structures. Update the partial declarations that extend a generated struct to the new form:

// Slice: struct Point { int x; int y; }
-public partial struct Point
+public partial record struct Point

// Slice: struct Person { string name; int age; }
-public partial class Person
+public sealed partial record class Person

Asynchronous Invocations

Proxies no longer provide the begin_ and end_ methods, and Ice.AsyncResult has been removed. Call the Async method of the operation, which returns a Task:

-Ice.AsyncResult result = greeter.begin_greet("alice");
-string greeting = greeter.end_greet(result);
+string greeting = await greeter.greetAsync("alice");

Tie Classes

slice2cs no longer generates tie classes (GreeterTie_) and operations interfaces (GreeterOperations_), and Ice.TieBase has been removed. Derive your servant class from the generated skeleton class, and forward each operation to your implementation object:

-adapter.add(new GreeterTie_(new GreeterImpl()), Ice.Util.stringToIdentity("greeter"));
+adapter.add(new GreeterServant(new GreeterImpl()), Ice.Util.stringToIdentity("greeter"));

public class GreeterServant : GreeterDisp_
{
    private readonly GreeterImpl _impl;

    public GreeterServant(GreeterImpl impl) => _impl = impl;

    public override string greet(string name, Ice.Current current) => _impl.greet(name, current);
}

Plug-in Factories

Ice.Util.registerPluginFactory has been removed. In Ice 3.8, you install a plug-in by adding its factory to the pluginFactories property of the InitializationData you pass to Ice.Util.initialize:

-Ice.Util.registerPluginFactory("IceDiscovery", new IceDiscovery.PluginFactory(), true);
-Ice.Communicator communicator = Ice.Util.initialize(ref args);
+var initData = new Ice.InitializationData
+{
+    properties = new Ice.Properties(ref args),
+    pluginFactories = [new IceDiscovery.PluginFactory()]
+};
+Ice.Communicator communicator = Ice.Util.initialize(initData);

• IceDiscovery.PluginFactory and IceLocatorDiscovery.PluginFactory go in pluginFactories, as shown above.
• IceSSL.PluginFactory goes away: the SSL transport is part of the ZeroC.Ice assembly.

The PluginFactory interface has a new pluginName property, which gives the name of the plug-in this factory creates. Add this property to your own plug-in factories. See Plug-in API.

public class MyPluginFactory : Ice.PluginFactory
{
+    public string pluginName => "MyPlugin";
+
    public Ice.Plugin create(Ice.Communicator communicator, string name, string[] args) =>
        new MyPlugin(communicator);
}

Continuations in Asynchronous Code

The threads of an Ice thread pool no longer set a SynchronizationContext. In Ice 3.7, this synchronization context ran the continuation of an await made in an Ice thread pool thread in the same Ice thread pool, unless the code called ConfigureAwait(false). In Ice 3.8, when a servant awaits a proxy invocation that is not yet complete, the continuation runs in a .NET thread pool thread.

Review the asynchronous code of your servants. Code that relied on an Ice thread pool to limit the number of threads that execute these continuations, such as a thread pool with a single thread, now needs its own synchronization.

Slice Metadata

• slice2cs silently ignores metadata with the clr: prefix, as it does metadata for other languages. Replace this prefix with cs::

  Diff

  -["clr:generic:List"] sequence<string> StringList;
  +["cs:generic:List"] sequence<string> StringList;

• cs:attribute applies only to enums, enumerators, constants and fields; slice2cs ignores it elsewhere, with a warning. Put the attribute of a class, struct, exception or interface on a partial declaration of the generated type in your own source file:

  Diff

  -["cs:attribute:System.Runtime.InteropServices.StructLayout(System.Runtime.InteropServices.LayoutKind.Sequential)"]
  struct Point { int x; int y; }

  C#

  [System.Runtime.InteropServices.StructLayout(System.Runtime.InteropServices.LayoutKind.Sequential)]
  public partial record struct Point;

• The cs:serializable, cs:tie and cs:implements directives have been removed; slice2cs ignores them with a warning. Remove them from your Slice definitions. If you relied on cs:serializable, serialize the object in your own code. If you relied on cs:implements, declare the interface on a partial declaration of the generated type in your own source file.

See Slice Metadata Directives for the metadata directives of Ice 3.8.

Java Mapping

Java 17

Ice for Java 3.8 requires Java 17.

Communicator Creation

Communicator is now a class with public constructors, and Util.initialize has fewer overloads. The InitializationData overload covers every case: if your application passed both command-line arguments and an InitializationData to Util.initialize, parse the arguments into the properties field first:

-Communicator communicator = Util.initialize(args, initData);
+initData.properties = new Properties(args, initData.properties);
+Communicator communicator = new Communicator(initData);

Thread Interrupts

Ice for Java now always supports thread interrupts: interrupting a thread blocked in an Ice call throws OperationInterruptedException. The Ice.ThreadInterruptSafe property, which enabled this behavior in Ice 3.7, has been removed.

Exceptions

Ice 3.8 removes the com.zeroc.Ice.Exception class, the base class of com.zeroc.Ice.LocalException in Ice 3.7. LocalException now derives directly from java.lang.RuntimeException, and com.zeroc.Ice.UserException derives from java.lang.Exception as in Ice 3.7. Catch LocalException where your code caught com.zeroc.Ice.Exception:

try {
     greeter.greet("alice");
-} catch (com.zeroc.Ice.Exception ex) {
+} catch (com.zeroc.Ice.LocalException ex) {
     ex.printStackTrace();
 }

Using null for a Struct or Enum

Ice 3.7 accepted null for a struct or enum parameter, return value, or field, and marshaled a default-constructed struct or the first enumerator in its place. Ice 3.8 requires a non-null value.

Slice Loaders

Ice 3.8 removes the ValueFactory and ValueFactoryManager interfaces. Set the sliceLoader field of InitializationData to create your own instances of Slice classes during unmarshaling. See Slice Loaders.

The java:package metadata is deprecated: slice2java warns when it sees it. Replace it with java:identifier on the module. java:identifier gives the full name of the Java package, where java:package gave a prefix. To keep the generated code unchanged, use the package that java:package produced:

-["java:package:com.example"]
+["java:identifier:com.example.VisitorCenter"]
module VisitorCenter

Your Ice.Package.<module> or Ice.Default.Package property then keeps locating the generated classes, as in Ice 3.7. If you move the module to another package, such as com.example.visitorcenter, these properties no longer apply: install a ModuleToPackageSliceLoader for this module instead:

var initData = new InitializationData();
initData.sliceLoader = new ModuleToPackageSliceLoader("::VisitorCenter", "com.example.visitorcenter");

try (Communicator communicator = new Communicator(initData)) {
    // ...
}

A Slice class with a compact ID also needs a Slice loader: pass its generated class to a ClassSliceLoader. Combine several loaders with a CompositeSliceLoader:

var initData = new InitializationData();
initData.sliceLoader = new CompositeSliceLoader(
    new ClassSliceLoader(AtmosphericConditions.class),
    new ModuleToPackageSliceLoader("::VisitorCenter", "com.example.visitorcenter"));

Dictionaries

A Slice dictionary now maps to a MATLAB dictionary. In Ice 3.7, it mapped to a containers.Map, or to a struct array with key and value fields when the key type was a Slice struct.

Create the dictionary with configureDictionary, giving the mapped key type and the mapped value type. For example, with dictionary<long, Employee> EmployeeMap, where Employee is a Slice struct:

-em = containers.Map('KeyType', 'int64', 'ValueType', 'any');
+em = configureDictionary('int64', 'Employee');
 em(31) = employee;

A dictionary keyed by a Slice struct takes the mapped struct as its key. With dictionary<Point, string> PointNames:

-names = struct('key', {}, 'value', {});
-names(1).key = Point(1, 2);
-names(1).value = 'start';
+names = configureDictionary('Point', 'string');
+names(Point(1, 2)) = 'start';

When the Slice value type is a sequence, a dictionary, a class or a proxy, the value type of the MATLAB dictionary is cell, and each value is a cell that holds the mapped value. Use curly braces to store and retrieve the value itself. With dictionary<string, Greeter*> GreeterMap:

-greeters = containers.Map('KeyType', 'char', 'ValueType', 'any');
-greeters('fr') = greeter;
-greeter = greeters('fr');
+greeters = configureDictionary('string', 'cell');
+greeters{'fr'} = greeter;
+greeter = greeters{'fr'};

A request context is a dictionary with string keys and string values:

-context = containers.Map('KeyType', 'char', 'ValueType', 'char');
+context = configureDictionary('string', 'string');
 context('language') = 'fr';
 greeting = greeter.greet('alice', context);

See Dictionaries for the value type that corresponds to each Slice type.

String Sequences

A generated proxy method now returns a sequence<string> as a string array and accepts a string array for a sequence<string> parameter. In Ice 3.7, a sequence<string> mapped to a cell array of character vectors. Review the code that indexes a returned sequence with curly braces.

names = directory.list();
-first = names{1};
+first = names(1);

Typed Arguments and Properties

A generated proxy method now validates the type of each argument, except for optional parameters. A generated class, exception or struct declares a typed property for each field, except for optional fields and fields that hold class instances.

Pass an empty array of the mapped type for a null proxy or a null class instance. In a typed property, represent a null proxy with an empty array of the proxy type, and an empty sequence with an empty array of the mapped sequence type:

-registry.setGreeter([]);
-entry.greeter = [];
-entry.weights = [];
+registry.setGreeter(GreeterPrx.empty);
+entry.greeter = GreeterPrx.empty;
+entry.weights = int32.empty;

Struct Properties

In a generated class, exception or struct, a non-optional field of Slice struct type is now empty by default. In Ice 3.7, it held a new instance of the mapped struct, so you could set the fields of this instance directly. Assign an instance first:

line = Line();
+line.start = Point();
 line.start.x = 10;

Slice Loaders

Ice 3.8 locates the generated class for a Slice class or exception through a Slice loader. The default Slice loader maps a Slice type ID such as ::M::Node to the MATLAB class M.Node. It cannot locate a class with a compact ID, or a class or exception whose name or enclosing module you rename with the matlab:identifier metadata: for these, create an Ice.ClassSliceLoader from the meta classes of the generated classes and give it to the communicator:

communicator = Ice.Communicator(args, SliceLoader = Ice.ClassSliceLoader(?Compact, ?CompactExt));

PHP Requirements

Ice for PHP 3.8 requires PHP 8.0 or later and runs on Linux and macOS. See Supported Platforms for Ice 3.8.3 for the tested PHP versions and operating systems.

Flattened Mapping

The flattened mapping, deprecated in Ice 3.7 and selected with slice2php --no-namespace, has been removed. Ice 3.8 provides only the namespace mapping.

To upgrade an application that uses the flattened mapping:

• Remove the --no-namespace and -n options from your slice2php commands, then recompile your Slice files.
• Replace each flattened name with its namespaced name. The flattened mapping joined the Slice module names and the type name with underscores, such as VisitorCenter_GreeterPrxHelper; the namespace mapping maps each Slice module to a PHP namespace, such as VisitorCenter\GreeterPrxHelper. The same rule applies to the functions and classes of the Ice runtime: Ice_initialize becomes Ice\initialize, and Ice_InitializationData becomes Ice\InitializationData.
• Replace the Ice_Unset constant, which marks an optional value as not set, with Ice\None.

-$communicator = Ice_initialize($argv);
-$greeter = VisitorCenter_GreeterPrxHelper::uncheckedCast($proxy);
+$communicator = Ice\initialize($argv);
+$greeter = VisitorCenter\GreeterPrxHelper::uncheckedCast($proxy);

Using null for a Struct

When you passed null where an operation expects a Slice struct, Ice 3.7 marshaled an instance of the struct created with its default constructor. Ice 3.8 throws InvalidArgumentException from the proxy invocation. The same rule applies to a struct nested in another struct, a class, a sequence or a dictionary.

Pass an instance of the struct:

-$greeter->setLocation(null);
+$greeter->setLocation(new VisitorCenter\Location);

PHP Value Factories

Ice for PHP 3.8 has no value factories and no Slice loaders: when it unmarshals a Slice class, it always creates an instance of the class generated by slice2php. Remove your value factories and the calls that register them with getValueFactoryManager.

ice.hide_profiles

The ice.hide_profiles directive has been removed: remove it from your PHP configuration. To keep the PHP settings of an application private, run each application in its own PHP-FPM pool. See Profiles in PHP.

Loading Slice Files

Ice.loadSlice now takes a single argument: a list that holds one string per compiler argument. Ice 3.7 accepted a command string, optionally followed by such a list.

-Ice.loadSlice("-I. Greeter.ice")
-Ice.loadSlice("-I.", ["Greeter.ice"])
+Ice.loadSlice(["-I.", "Greeter.ice"])

Like slice2py, Ice.loadSlice no longer accepts the --all option. Pass every Slice file of your application, including the files that your other Slice files include:

-Ice.loadSlice("--all Root.ice")
+Ice.loadSlice(["Foo.ice", "Bar.ice", "Root.ice"])

See Code Generation.

Arguments of Ice.initialize

Ice.initialize takes either an argument list, such as Ice.initialize(sys.argv), or an Ice.InitializationData object as the initData keyword argument.

To combine command-line arguments with an InitializationData object, create the properties of this object from the arguments:

initData = Ice.InitializationData()
 initData.logger = MyLogger()
-communicator = Ice.initialize(sys.argv, initData)
+initData.properties = Ice.createProperties(sys.argv, initData.properties)
+communicator = Ice.initialize(initData=initData)

To combine command-line arguments with a configuration file, add --Ice.Config to the arguments:

-communicator = Ice.initialize(sys.argv, "config.client")
+sys.argv.append("--Ice.Config=config.client")
+communicator = Ice.initialize(sys.argv)

Optional Values

Ice 3.8 removes Ice.Unset and uses None in its place: Ice returns None for an optional parameter, return value or field without a value, an optional field with no default value in Slice is initially None, and a None you pass for an optional parameter or field means "not set".

-if greeting is not Ice.Unset:
+if greeting is not None:
     print(greeting)

Enumerations

A generated enumeration now derives from the enum.Enum class of Python, and Ice 3.8 removes Ice.EnumBase. An enumerator keeps its name and value attributes. Update the code that uses the following:

• Color.valueOf(n) becomes Color(n).
• The <, <=, > and >= operators no longer work on enumerators: compare the value attributes.
• str(Color.Red) now returns Color.Red; use Color.Red.name to get Red.

-color = Color.valueOf(n)
-if color < Color.Blue:
+color = Color(n)
+if color.value < Color.Blue.value:
     ...

Using None for a Struct

Marshaling None for a struct parameter, return value, or field that is not optional now fails with a ValueError. Ice 3.7 marshaled a default-constructed struct in this case. Pass an instance of the struct:

-clock.setTime(None)
+clock.setTime(TimeOfDay())

Asynchronous Invocations

The synchronous proxy methods work as in Ice 3.7. For asynchronous invocations, we recommend the Async methods with asyncio: create the communicator with the running event loop, then await the invocation. The code is as simple as with the synchronous methods, and the event loop can run other tasks while the invocation is in progress:

async def main():
    async with Ice.Communicator(sys.argv, eventLoop=asyncio.get_running_loop()) as communicator:
        greeter = GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")
        greeting = await greeter.greetAsync("alice")
        print(greeting)

asyncio.run(main())

Ice 3.8 removes the begin_ and end_ methods and Ice.AsyncResult. Without an event loop, an Async method returns an Ice.InvocationFuture, as in Ice 3.7:

-result = greeter.begin_greet("alice")
-greeting = greeter.end_greet(result)
+future = greeter.greetAsync("alice")
+greeting = future.result()

Replace the _response and _ex callbacks of a begin_ method with a callback registered with add_done_callback on the future, and the _sent callback with a callback registered with add_sent_callback, which now receives a single argument:

-def sent(future, sentSynchronously):
+def sent(sentSynchronously):
     ...

 future.add_sent_callback(sent)

Sequence Metadata

The python:seq:list, python:seq:tuple, python:seq:default and python:default metadata directives have been removed; slice2py ignores them with a warning. Replace python:seq:list and python:seq:tuple with python:list and python:tuple, and remove python:seq:default and python:default. See the sequence mapping.

-["python:seq:tuple"] sequence<string> StringSeq;
+["python:tuple"] sequence<string> StringSeq;

Ice 3.8 removes Ice.createArray and Ice.createNumPyArray, the factory functions that Ice 3.7 provided for the python:memoryview metadata. To map a sequence to an array.array or to a NumPy array, use the python:array.array or python:numpy.ndarray metadata instead:

-["python:memoryview:MyModule.createIntArray"] sequence<int> IntSeq;
+["python:numpy.ndarray"] sequence<int> IntSeq;

A factory function for python:memoryview now takes two parameters, the memory view and the element type; Ice 3.7 passed a third parameter, copy.

Marshaled Results

The marshaled-result metadata no longer affects the generated Python code: slice2py no longer generates the MarshaledResult helper methods, and the servant method returns the result itself:

def getNode(self, current):
-    return Demo.Tree.GetNodeMarshaledResult(self._node, current)
+    return self._node

Keep the marshaled-result metadata in a Slice file that you also compile for another language mapping, where it still applies.

Loading Slice Files

Ice::loadSlice now takes a single argument: an array that holds one string per compiler argument. Ice 3.7 accepted a command string, optionally followed by such an array.

-Ice::loadSlice("-I. Foo.ice")
-Ice::loadSlice("-I.", ["Foo.ice"])
+Ice::loadSlice(["-I.", "Foo.ice"])

Arguments of Ice::initialize

Ice::initialize now takes at most one argument, either an argument array or an Ice::InitializationData object.

To combine command-line arguments with an Ice::InitializationData object, create its properties from the arguments, with the properties it already holds as the defaults:

-Ice::initialize(ARGV, initData) do |communicator|
+initData.properties = Ice::createProperties(ARGV, initData.properties)
+Ice::initialize(initData) do |communicator|
     ...
 end

To combine command-line arguments with a configuration file, add --Ice.Config to the arguments:

-Ice::initialize(ARGV, "config.client") do |communicator|
+Ice::initialize(ARGV + ["--Ice.Config=config.client"]) do |communicator|
     ...
 end

The block given to Ice::initialize now takes a single parameter, the communicator. Ice 3.7 also accepted a block with a second parameter that received the remaining command-line arguments. Ice::initialize and Ice::createProperties remove the options they recognize from the array you pass, so read the remaining arguments from that array:

-Ice::initialize(ARGV) do |communicator, args|
-    run(communicator, args)
+Ice::initialize(ARGV) do |communicator|
+    run(communicator, ARGV)
 end

Optional Values

Ice::Unset is now an alias for nil: Ice returns nil for an optional parameter, return value or field without a value, an optional field with no default value in Slice is initially nil, and a nil you pass for an optional parameter or field means "not set". Code that compares with Ice::Unset keeps working.

Using nil for a Struct

A non-optional struct parameter or field no longer accepts nil. Ice 3.7 marshaled a default-constructed struct in its place. Pass an instance of the struct:

-greeter.setLocation(nil)
+greeter.setLocation(VisitorCenter::Location.new)

async/await and Structured Concurrency

Ice for Swift now requires Swift 6.1, uses async/await and structured concurrency, and no longer depends on PromiseKit. Every proxy invocation is async:

-let greeting = try greeter.greet(name)
+let greeting = try await greeter.greet(name)
print(greeting)

-firstly {
-    greeter.greetAsync(name)
-}.get { greeting in
-    print("\(greeting)")
-}
+let greeting = try await greeter.greet(name)
print(greeting)

Every operation of a skeleton protocol is now async throws, and the amd metadata directive no longer affects the generated code. A servant method that completes synchronously and throws no exception keeps its Ice 3.7 signature, since a method can omit async and throws:

func greet(name: String, current _: Ice.Current) -> String {
    ...
}

A servant method that implemented an amd operation with PromiseKit becomes an async method:

-func greetAsync(name: String, current _: Ice.Current) -> Promise<String> {
+func greet(name: String, current _: Ice.Current) async throws -> String {
    ...
}

Sendable Servants

Skeleton protocols inherit Sendable from Ice.Dispatcher, and the object adapter dispatches each request in its own task, so several tasks can call the same servant concurrently. Implement a servant with mutable state as an actor, or as a final class that synchronizes access to its state and is declared @unchecked Sendable.

-class MFile: File {
+actor MFile: File {
    private var lines: [String] = []

    func write(text: [String], current _: Ice.Current) {
        lines = text
    }
}

Removed Dispatch Structs

The generated dispatch structs, such as GreeterDisp, have been removed: you now add an object that implements the skeleton protocol directly to the object adapter.

-try adapter.add(servant: GreeterDisp(Chatbot()), id: Ice.Identity(name: "greeter"))
+try adapter.add(servant: Chatbot(), id: Ice.Identity(name: "greeter"))