215 строки
8.4 KiB
Markdown
215 строки
8.4 KiB
Markdown
# Breaking changes in .NET
|
|
|
|
Reference: https://github.com/xamarin/xamarin-macios/issues/13087
|
|
|
|
## The SDK assemblies have been renamed.
|
|
|
|
We've renamed the SDK assemblies like this:
|
|
|
|
* `Xamarin.iOS.dll` -> `Microsoft.iOS.dll`
|
|
* `Xamarin.TVOS.dll` -> `Microsoft.tvOS.dll`
|
|
* `Xamarin.MacCatalyst.dll` -> `Microsoft.MacCatalyst.dll`
|
|
* `Xamarin.Mac.dll` -> `Microsoft.macOS.dll`
|
|
|
|
This will affect:
|
|
|
|
* Code using reflection with hardcoded assembly name.
|
|
* [Custom linker configuration files](https://docs.microsoft.com/en-us/xamarin/cross-platform/deploy-test/linker), since they contain the assembly name.
|
|
|
|
## Removed `System.nint` and `System.nuint`
|
|
|
|
The two types `System.nint` and `System.nuint` (which despite their `System`
|
|
namespace were shipped with Xamarin.iOS/Xamarin.Mac) have been removed in
|
|
favor of the C# 9 `nint` and `nuint` types (these map to `System.IntPtr` and
|
|
`System.UIntPtr` respectively).
|
|
|
|
* Code that uses these types with the full namespace (`System.nint` / `System.nuint`) won't compile.
|
|
|
|
Fix: remove the namespace, and use `nint` / `nuint` only.
|
|
|
|
* Code that overloads on `System.IntPtr`/`System.UIntPtr` and `nint`/`nuint`won't compile.
|
|
|
|
Example:
|
|
|
|
```csharp
|
|
public void DoSomething (IntPtr value) {}
|
|
public void DoSomething (nint value) {}
|
|
```
|
|
|
|
Fix: one of the overloads would have to be either renamed or removed.
|
|
|
|
Reference: https://github.com/xamarin/xamarin-macios/issues/10508
|
|
|
|
## Removed `System.nfloat`
|
|
|
|
The `System.nfloat` type has been removed in favor of the
|
|
`System.Runtime.InteropServices.NFloat` type.
|
|
|
|
In order to make existing code compile as much as possible, we're adding a
|
|
global using directive to C# projects, so that using `nfloat` as a type name
|
|
continues to work:
|
|
|
|
```csharp
|
|
global using nfloat = System.Runtime.InteropServices.NFloat;
|
|
```
|
|
|
|
If this global using directive is undesirable, it can be turned off by setting
|
|
a `NoNFloatUsing=true` property in the project file.
|
|
|
|
Also, we're only adding the global using directive for projects that target C#
|
|
10 or later (since that's the first C# version that supports global using
|
|
directives). Projects that use an older C# version will have to manually add
|
|
the using directive to every source file.
|
|
|
|
There are a few other source code incompatibilities:
|
|
|
|
* Any code that refers to the full typename (`System.nfloat`) will have to be
|
|
modified to just use `nfloat`, or the new full typename
|
|
(`System.Runtime.InteropServices.NFloat`).
|
|
* The `nfloat.CopyArray` methods don't exist in `NFloat`. The code needs to be
|
|
rewritten to use `Buffer.CopyMemory` instead.
|
|
|
|
## System.NMath moved to ObjCRuntime.NMath
|
|
|
|
The `NMath` type moved from the `System` namespace to the `ObjCRuntime` namespace.
|
|
|
|
* Code that uses the `NMath` type won't compile unless the `ObjCRuntime` namespace is imported.
|
|
|
|
Fix: add `using ObjCRuntime` to the file in question, or as a global using directive.
|
|
|
|
## NSObject.Handle and INativeObject.Handle changed type from System.IntPtr to ObjCRuntime.NativeHandle
|
|
|
|
The `NSObject.Handle` and `INativeObject.Handle` properties changed type from
|
|
`System.IntPtr` to `ObjCRuntime.NativeHandle`. This also means that numerous
|
|
other parameters and return values change type in the same way; most important
|
|
are the constructors that previously took a `System.IntPtr`, or
|
|
`System.IntPtr` + `bool`. Both variants now take a `ObjCRuntime.NativeHandle`
|
|
instead.
|
|
|
|
This is so that we can support API that take native-sized integers (`nint` /
|
|
`nuint` - which map to `System.[U]IntPtr`) while at the same time have a
|
|
different overload that takes a handle.
|
|
|
|
The most common examples are constructors - all `NSObject` subclasses have a
|
|
constructor that (now) take a single `ObjCRuntime.NativeHandle` parameter, and
|
|
some types also need to expose a constructor that take a native-sized integer.
|
|
For instance `NSMutableString` has a `nint capacity` constructor, which
|
|
without this type change would be impossible to expose correctly.
|
|
|
|
There are implicit conversions between `System.IntPtr` and
|
|
`ObjCRuntime.NativeHandle`, so most code should compile without changes.
|
|
|
|
One major caveat however is that user code with an `IntPtr` constructor like
|
|
the following:
|
|
|
|
```csharp
|
|
public class MyViewController : UIViewController {
|
|
public MyViewController (IntPtr handle) : base (handle) {}
|
|
}
|
|
```
|
|
|
|
will have to be updated to:
|
|
|
|
|
|
```csharp
|
|
public class MyViewController : UIViewController {
|
|
public MyViewController (NativeHandle handle) : base (handle) {}
|
|
}
|
|
```
|
|
|
|
Note that code that has the `IntPtr` constructor will compile just fine (no
|
|
warnings nor errors), but it will fail at runtime.
|
|
|
|
## The ObjCRuntime.Arch enum and the Runtime.Arch property have been removed.
|
|
|
|
These APIs are used to determine whether we're executing in the simulator or
|
|
on a device. Neither apply to a Mac Catalyst app, so they've been removed.
|
|
|
|
Any code that these APIs will have to be ported to not use these APIs.
|
|
|
|
## The SceneKit.SCNMatrix4 matrix is transposed in memory.
|
|
|
|
The managed SCNMatrix4 struct used to be a row-major matrix, while the native
|
|
SCNMatrix4 struct is a column-major matrix. This difference in the memory
|
|
representation meant that matrices would often have to be transposed when
|
|
interacting with the platform.
|
|
|
|
In .NET, we've changed the managed SCNMatrix4 to be a column-major matrix, to
|
|
match the native version. This means that any transposing that's currently
|
|
done when accessing Apple APIs has to be undone.
|
|
|
|
## Some types were moved from the CoreServices namespace to the CFNetwork namespace.
|
|
|
|
The following types:
|
|
|
|
* CFHTTPStream
|
|
* CFHTTPMessage
|
|
* CFHTTPAuthentication
|
|
|
|
were moved from the CoreServices namespace to the CFNetwork namespace.
|
|
|
|
This requires adding a `using CFNetwork;` statement to any files that uses these types.
|
|
|
|
## Numerous types in ModelIO have corrected their API
|
|
|
|
When we originally implemented ModelIO, we didn't notice at first that some of
|
|
the matrix types Apple used had a column-major layout, so we accidentally
|
|
bound many API with the wrong matrix type (with a row-major layout). This was
|
|
troublesome, because many matrices had to be transposed for code to work
|
|
correctly. We re-implemented all the API with the correct matrix type, but
|
|
named differently (and worse). In .NET we've removed all the incorrectly bound
|
|
API, and we've renamed the correctly bound API to use the best name (usually
|
|
reflecting how Apple named these APIs).
|
|
|
|
This affects methods and properties on the following classes:
|
|
|
|
* MDLCamera
|
|
* MDLMaterialProperty
|
|
* MDLStereoscopicCamera
|
|
* MDLTransform
|
|
* MDLTransformComponent
|
|
|
|
## Removal of `Runtime.UseAutoreleasePoolInThreadPool`
|
|
|
|
Enabling or disabling this feature is not supported at runtime and must
|
|
be done using the MSBuild [`AutoreleasePoolSupport`](https://docs.microsoft.com/en-us/dotnet/core/run-time-config/threading#autoreleasepool-for-managed-threads)
|
|
property.
|
|
|
|
You can query if the build-time feature is enabled with the following code:
|
|
|
|
```csharp
|
|
AppContext.TryGetSwitch ("System.Threading.Thread.EnableAutoreleasePool", out var enabled);
|
|
```
|
|
|
|
## The types `NSFileProviderExtension` and `NSFileProviderExtensionFetchThumbnailsHandler` moved
|
|
|
|
The types `NSFileProviderExtension` and
|
|
`NSFileProviderExtensionFetchThumbnailsHandler` moved from the `UIKit`
|
|
namespace to the `NSFileProvider` namespace (this is reflecting that Apple
|
|
originally added these types to `UIKit`, but then moved them to their own
|
|
namespace, `NSFileExtension`).
|
|
|
|
## The 'Foundation.MonoTouchException' and 'Foundation.ObjCException' types have been renamed/moved to 'ObjCRuntime.ObjCException'.
|
|
|
|
The type `Foundation.MonoTouchException` (for iOS, tvOS and Mac Catalyst) and
|
|
the type `Foundation.ObjCException` (for macOS) have been renamed/moved to
|
|
`ObjCRuntime.ObjCException`. Both types had the exact same functionality: they
|
|
were wrapping a native NSException, and were renamed so that we have identical
|
|
API and behavior on all platforms.
|
|
|
|
## The type 'CFNetwork.MessageHandler' has been removed.
|
|
|
|
The type 'CFNetwork.MessageHandler' has been removed. Please use
|
|
'System.Net.Http.CFNetworkHandler' or the more recent
|
|
'Foundation.NSUrlSessionHandler' instead.
|
|
|
|
## Changed name of the Info.plist entry with our version number.
|
|
|
|
We add an entry to the app's Info.plist with the version number used to build
|
|
the app. In .NET, we've changed the name of this entry from `com.xamarin.ios`
|
|
to `com.microsoft.<platform in lower case>` (for instance `com.microsoft.tvos`
|
|
for tvOS apps).
|
|
|
|
The version format has also changed, from "X.Y.Z.W (`branch`: `hash`)" to the
|
|
semantic versioning we use for .NET: "X.Y.Z-`branch`.Z+sha.`hash`".
|