This is an automated email from the ASF dual-hosted git repository. dmagda pushed a commit to branch IGNITE-7595 in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/IGNITE-7595 by this push: new ba6fbe2 ported .NET-specific documentation pages - configuration, deployment and standalone nodes. ba6fbe2 is described below commit ba6fbe25e1825e2a34f70e8f5f56826157d7cde6 Author: Denis Magda <dma...@gridgain.com> AuthorDate: Mon Sep 28 16:26:01 2020 -0700 ported .NET-specific documentation pages - configuration, deployment and standalone nodes. --- docs/_data/toc.yaml | 28 ++++ docs/_docs/net-specific/configuration-options.adoc | 176 +++++++++++++++++++++ docs/_docs/net-specific/deployment-options.adoc | 138 ++++++++++++++++ docs/_docs/net-specific/standalone-nodes.adoc | 116 ++++++++++++++ 4 files changed, 458 insertions(+) diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml index 2616397..8db5154 100644 --- a/docs/_data/toc.yaml +++ b/docs/_data/toc.yaml @@ -421,6 +421,34 @@ url: extensions-and-integrations/streaming/zeromq-streamer - title: Twitter Streamer url: extensions-and-integrations/streaming/twitter-streamer +- title: C# and .NET Specific + items: + - title: Configuration Options + url: net-specific/configuration-options + - title: Deployment Options + url: net-specific/deployment-options + - title: Standalone Nodes + url: net-specific/standalone-nodes + - title: Logging + url: net-specific/logging + - title: LINQ + url: net-specific/linq + - title: Java Services Execution + url: net-specific/java-services-execution + - title: Plugins + url: net-specific/plugins + - title: Serialization + url: net-specific/serialization + - title: Cross-Platform Support + url: net-specific/cross-platform-support + - title: Platform Interoperability + url: net-specific/platform-interoperability + - title: Remote Assembly Loading + url: net-specific/remote-assembly-loading + - title: Troubleshooting + url: net-specific/troubleshooting + - title: Integrations + url: net-specific/integrations - title: Plugins url: plugins - title: SQL Reference diff --git a/docs/_docs/net-specific/configuration-options.adoc b/docs/_docs/net-specific/configuration-options.adoc new file mode 100644 index 0000000..518c83e --- /dev/null +++ b/docs/_docs/net-specific/configuration-options.adoc @@ -0,0 +1,176 @@ += Ignite.NET Configuration Options + +== Overview + +Ignite.NET nodes can be configured in a variety of ways and then started via configuration-specific `Ignition.Start*` methods. + +== Configure Programmatically in C# + +Use the `Ignition.Start(IgniteConfiguration)` method to configure an Ignite.NET node from your C# application. + +[tabs] +-- +tab:Sample C# Configuration[] +[source,csharp] +---- +Ignition.Start(new IgniteConfiguration +{ + DiscoverySpi = new TcpDiscoverySpi + { + IpFinder = new TcpDiscoveryStaticIpFinder + { + Endpoints = new[] {"127.0.0.1:47500..47509"} + }, + SocketTimeout = TimeSpan.FromSeconds(0.3) + }, + IncludedEventTypes = EventType.CacheAll, + JvmOptions = new[] { "-Xms1024m", "-Xmx1024m" } +}); +---- +-- + +== Configure With Application or Web Config Files + +`Ignition.StartFromApplicationConfiguration` methods read configuration from `Apache.Ignite.Core.IgniteConfigurationSection` +of the app.config or web.config files. + +The `IgniteConfigurationSection.xsd` schema file can be found next to Apache.Ignite.Core.dll in the binary distribution, +and in `Apache.Ignite.Schema` NuGet package. Include it in your project with `None` build action to enable IntelliSense +in Visual Studio while editing `IgniteConfigurationSection` in the config files. + +[tabs] +-- +tab:Configure in app.config[] +[source,xml] +---- +<configuration> + <configSections> + <section name="igniteConfiguration" type="Apache.Ignite.Core.IgniteConfigurationSection, Apache.Ignite.Core" /> + </configSections> + + <runtime> + <gcServer enabled="true"/> + </runtime> + + <igniteConfiguration xmlns="http://ignite.apache.org/schema/dotnet/IgniteConfigurationSection" gridName="myGrid1"> + <discoverySpi type="TcpDiscoverySpi"> + <ipFinder type="TcpDiscoveryStaticIpFinder"> + <endpoints> + <string>127.0.0.1:47500..47509</string> + </endpoints> + </ipFinder> + </discoverySpi> + + <cacheConfiguration> + <cacheConfiguration cacheMode='Replicated' readThrough='true' writeThrough='true' /> + <cacheConfiguration name='secondCache' /> + </cacheConfiguration> + + <includedEventTypes> + <int>42</int> + <int>TaskFailed</int> + <int>JobFinished</int> + </includedEventTypes> + + <userAttributes> + <pair key='myNode' value='true' /> + </userAttributes> + + <JvmOptions> + <string>-Xms1024m</string> + <string>-Xmx1024m</string> + </JvmOptions> + </igniteConfiguration> +</configuration> +---- +tab:Use in C#[] +[source,csharp] +---- +var ignite = Ignition.StartFromApplicationConfiguration("igniteConfiguration"); +---- +-- + +[NOTE] +==== +[discrete] +To add the `IgniteConfigurationSection.xsd` schema file to a Visual Studio project go to `Projects` menu and click on +`Add Existing Item...` menu item. After that locate `IgniteConfigurationSection.xsd` inside of the Apache Ignite distribution +and pick it up. Alternatively, install NuGet package: `Install-Package Apache.Ignite.Schema`. This will add an xsd file to +the project automatically. To improve editing, make sure that `Statement Completion` options are enabled in +`Tools - Options - Text Editor - XML`. +==== + +=== Ignite Configuration Section Syntax + +The configuration section maps directly to `IgniteConfiguration` class: + +* Simple properties (strings, primitives, enums) map to XML attributes (attribute name = camelCased C# property name). +* Complex properties map to nested XML elements (element name = camelCased C# property name). +* When a complex property is an interface or abstract class, `type` attribute is used to specify the type, using *assembly-qualified name*. For built-in types (like TcpDiscoverySpi in the code sample above) assembly name and namespace can be omitted. +* When in doubt, consult the schema in `IgniteConfigurationSection.xsd`. + +== Configure With Spring XML + +Spring XML enables the native java-based Ignite configuration method. A Spring config file can be provided via +the `Ignition.Start(string)` method or the `IgniteConfiguration.SpringConfigUrl` property. This configuration method +is useful when some Java property is not natively supported by Ignite.NET. + +When the `IgniteConfiguration.SpringConfigUrl` property is used, the Spring config is loaded first, and other +`IgniteConfiguration` properties are applied on top of it. + +[tabs] +-- +tab:Configure With Spring XML[] +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> + +<beans xmlns="http://www.springframework.org/schema/beans" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:util="http://www.springframework.org/schema/util" + xsi:schemaLocation="http://www.springframework.org/schema/beans + http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/util + http://www.springframework.org/schema/util/spring-util.xsd"> + <bean id="grid.cfg" class="org.apache.ignite.configuration.IgniteConfiguration"> + <property name="localHost" value="127.0.0.1"/> + <property name="gridName" value="grid1"/> + <property name="userAttributes"> + <map> + <entry key="my_attr" value="value1"/> + </map> + </property> + + <property name="cacheConfiguration"> + <list> + <bean class="org.apache.ignite.configuration.CacheConfiguration"> + <property name="name" value="cache1"/> + <property name="startSize" value="10"/> + </bean> + </list> + </property> + + <property name="discoverySpi"> + <bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi"> + <property name="ipFinder"> + <bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.vm.TcpDiscoveryVmIpFinder"> + <property name="addresses"> + <list> + <value>127.0.0.1:47500..47509</value> + </list> + </property> + </bean> + </property> + <property name="socketTimeout" value="300" /> + </bean> + </property> + </bean> +</beans> +---- +tab:Use in C#[] +[source,csharp] +---- +var ignite = Ignition.Start("spring-config.xml"); +---- +-- + diff --git a/docs/_docs/net-specific/deployment-options.adoc b/docs/_docs/net-specific/deployment-options.adoc new file mode 100644 index 0000000..05813e7 --- /dev/null +++ b/docs/_docs/net-specific/deployment-options.adoc @@ -0,0 +1,138 @@ += Application Deployment Options + +== Overview + +Apache Ignite.NET consists of .NET assemblies and Java jar files. The .NET assemblies are referenced by your project and +are copied to an output folder during the build automatically. The JAR files should be copied manually. +Ignite.NET discovers them via the `IgniteHome` or `JvmClasspath` settings. + +This page introduces several most-commonly used deployment options of Ignite.NET nodes. + +== Full Binary Package Deployment + +* Copy the https://ignite.apache.org[whole Ignite distribution package, window=_blank] along with your application +* Set the `IGNITE_HOME` environment variable or `IgniteConfiguration.IgniteHome` setting to point to that folder + +== NuGet Deployment + +The post-build event is updated automatically during the Ignite.NET NuGet package installation to copy jar files to +`Libs` folder in the output directory (see link:quick-start/dotnet[Getting Started]). +Make sure to include that `Libs` folder when distributing your binaries. + +Make sure `IGNITE_HOME` is not set globally. Normally you don't need to set `IGNITE_HOME` with NuGet, except for +ASP.NET deployments (see below). + +[tabs] +-- +tab:Post-Build Event[] +[source,shell] +---- +if not exist "$(TargetDir)Libs" md "$(TargetDir)Libs" +xcopy /s /y "$(SolutionDir)packages\Apache.Ignite.1.6.0\Libs\*.*" "$(TargetDir)Libs" +---- +-- + +== Custom Deployment + +The JAR files are located in the `libs` folder of the binary distribution and NuGet package. +The minimum set of jars for Ignite.NET is: + +* `ignite-core-{VER}.jar` +* `cache-api-1.0.0.jar` +* `ignite-indexing` folder (if SQL queries are used) +* `ignite-spring` folder (if a Spring XML configuration is used) + +=== Deploying JARs to a default location: + +* Copy the JAR files to the `Libs` folder next to Apache.Ignite.Core.dll +* Do not set the `IgniteConfiguration.JvmClasspath`, `IgniteConfiguration.IgniteHome` properties and `IGNITE_HOME` environment variable + +=== Deploying jar files to an arbitrary location: + +* Copy the JAR files somewhere +* Set the `IgniteConfiguration.JvmClasspath` property to a semicolon-separated string of paths for each jar file +* Do not set the `IGNITE_HOME` environment variable and `IgniteConfiguration.IgniteHome` property + +[tabs] +-- +tab:IgniteConfiguration.JvmClasspath Example[] +[source,shell] +---- +c:\ignite-jars\ignite-core-1.5.0.final.jar;c:\ignite-jars\cache-api-1.0.0.jar +---- +-- + +== ASP.NET Deployment + +`JvmClasspath` or `IgniteHome` have to be explicitly set when using Ignite in a web environment (IIS and IIS Express), +because DDL files are copied to temporary folders, and Ignite can not locate JAR files automatically. + +You can set `IgniteHome` like this in ASP.NET environment: + +[tabs] +-- +tab:C#[] +[source,csharp] +---- +Ignition.Start(new IgniteConfiguration +{ + IgniteHome = HttpContext.Current.Server.MapPath(@"~\bin\") +}); +---- +-- + +Alternatively, `IGNITE_HOME` can be set globally. Add this line at the top of the `Application_Start` method in `Global.asax.cs`: + +[tabs] +-- +tab:C#[] +[source,csharp] +---- +Environment.SetEnvironmentVariable("IGNITE_HOME", HttpContext.Current.Server.MapPath(@"~\bin\")); +---- +-- + +Finally, you can use the following method to populate `JvmClasspath`: +[tabs] +-- +tab:C#[] +[source,csharp] +---- +static string GetDefaultWebClasspath() +{ + var dir = HttpContext.Current.Server.MapPath(@"~\bin\libs"); + + return string.Join(";", Directory.GetFiles(dir, "*.jar")); +} +---- +-- + +== IIS Application Pool Lifecycle, AppDomains, and Ignite.NET + +There is a known problem with IIS. When a web application is restarted due to code changes or a manual restart, +the application pool process remains alive, while AppDomain gets recycled. + +Ignite.NET automatically stops when AppDomain is unloaded. However, a new domain may be started when old one is still +unloading. So the node from the old domain can have an `IgniteConfiguration.IgniteInstanceName` conflict with a node from the new domain. + +To fix this issue make sure to either assign a unique `IgniteInstanceName`, or set +`IgniteConfiguration.AutoGenerateIgniteInstanceName` property to `true`. + +[tabs] +-- +tab:Use in C#[] +[source,csharp] +---- +var cfg = new IgniteConfiguration { AutoGenerateIgniteInstanceName = true }; +---- +tab:web.config[] +[source,xml] +---- +<igniteConfiguration autoGenerateIgniteInstanceName="true"> + ... +</igniteConfiguration> +---- +-- + +Refer to the http://stackoverflow.com/questions/42961879/how-do-i-retrieve-a-started-ignite-instance-when-a-website-restart-occurs-in-iis/[following StackOverflow discussion, window=_blank] +for more details. diff --git a/docs/_docs/net-specific/standalone-nodes.adoc b/docs/_docs/net-specific/standalone-nodes.adoc new file mode 100644 index 0000000..d5030ab --- /dev/null +++ b/docs/_docs/net-specific/standalone-nodes.adoc @@ -0,0 +1,116 @@ += Ignite.NET Standalone Nodes + +== Overview + +An Ignite.NET node can be started within the code of a .NET application by using `Ignition.Start()` or as a separate +process with `Apache.Ignite.exe` executable located under `{apache_ignite_release}\platforms\dotnet\bin` folder. +Internally `Apache.Ignite.exe` references `Apache.Ignite.Core.dll` and uses `Ignition.Start()` as you would normally do, +and can be configured with command line arguments, listed below, by passing them as command line options or setting directly +in `Apache.Ignite.exe.config` file. + +Usually, you start server nodes in the standalone mode. An Ignite cluster is a group of server nodes interconnected +together in order to provide shared resources like RAM and CPU to your applications. + +== Configure Standalone Node via Command Line + +Below you can see basic Ignite parameters that can be passed as command line arguments when a node is started with +`Apache.Ignite.exe` executable: + +[width="100%",cols="1,3",opts="header"] +|=== +|Command Line Argument |Description +|`-IgniteHome`| A path to Ignite installation directory (if not provided, the `IGNITE_HOME` environment variable is used) +|`-ConfigFileName`| A path to the app.config file (if not provided, `Apache.Ignite.exe.config` is used). +|`-ConfigSectionName`| The name of the `IgniteConfigurationSection` from a configuration file. +|`-SpringConfigUrl`| A path to a Spring configuration file. +|`-JvmDllPath`| A path to JVM library `jvm.dll` (if not provided, `JAVA_HOME` environment variable is used). +|`-JvmClasspath`| The classpath to pass to JVM started by Ignite.NET internally (use to enlist additional JAR files). +|`-SuppressWarnings`| Whether or not to print warnings. +|`-J<javaOption>`| Additional JVM options to be used during the initialization of the JVM. +|`-Assembly`| Additional .NET assemblies to be loaded. +|`-JvmInitialMemoryMB`| Initial Java heap size, in megabytes. Maps to the `-Xms` Java parameter. +|`-JvmMaxMemoryMB`| Maximum Java heap size, in megabytes. Maps to the `-Xmx` Java parameter. +|`/install`| Installs Ignite Windows service with provided options. +|`/uninstall`| Uninstalls Ignite Windows service. +|=== + + +[tabs] +-- +tab:Example[] +[source,shell] +---- +Apache.Ignite.exe -ConfigFileName=c:\ignite\my-config.xml -ConfigSectionName=igniteConfiguration -Assembly=c:\ignite\my-code.dll -J-Xms1024m -J-Xmx2048m +---- +-- + +== Configure Standalone Node via XML Files + +A standalone node can be configured with app.config XML or Spring XML (or both). Every command line argument, listed above, +can also be used in `Apache.Ignite.exe.config` under `appSettings` section: + +[tabs] +-- +tab:Apache.Ignite.exe.config[] +[source,xml] +---- +<configuration> + <configSections> + <section name="igniteConfiguration" type="Apache.Ignite.Core.IgniteConfigurationSection, Apache.Ignite.Core" /> + </configSections> + + <igniteConfiguration springConfigUrl="c:\ignite\spring.xml"> + <cacheConfiguration name="myCache" cacheMode="Replicated" /> + </igniteConfiguration> + + <appSettings> + <add key="Ignite.Assembly.1" value="my-assembly.dll"/> + <add key="Ignite.Assembly.2" value="my-assembly2.dll"/> + <add key="Ignite.ConfigSectionName" value="igniteConfiguration" /> + </appSettings> +</configuration> +---- +-- + +This example defines the `igniteConfiguration` section and uses it to start Ignite via the `Ignite.ConfigSectionName` setting. +It also references the Spring XML configuration file, whose settings will be added to the specified configuration. + +== Load User Assemblies + +Some Ignite APIs involve remote code execution and require you to load assemblies with your code into `Apache.Ignite.exe` +via `-Assembly` command line argument or `Ignite.Assembly` app setting. + +The following functionality requires a corresponding assembly to be loaded on all nodes: + +* ICompute (supports automatic loading, see link:net-specific/remote-assembly-loading[Remote Assembly Loading]) +* Scan Queries with filter +* Continuous Queries with filter +* ICache.Invoke methods +* ICache.LoadCache with filter +* IServices +* IMessaging.RemoteListen +* IEvents.RemoteQuery + +[NOTE] +==== +[discrete] +=== Missing User Assemblies +If a user assembly cannot be located a `Could not load file or assembly 'MyAssembly'` or one of its dependencies +exception will be thrown. + +Note, that it is also necessary to add any dependencies of the user assembly to the list. +==== + +== Ignite.NET as Windows Service + +`Apache.Ignite.exe` can be installed as a Windows Service so it is started automatically via `/install` command line argument. +All other command line arguments will be preserved and used each time the service starts. Use `/uninstall` to uninstall the service. + +[tabs] +-- +tab:Example[] +[source,shell] +---- +Apache.Ignite.exe /install -J-Xms513m -J-Xmx555m -ConfigSectionName=igniteConfiguration +---- +--