نام (NAME)

genxs - تولیدکننده سریالایزر XML در مونو (Mono)

خلاصه دستور (SYNOPSIS)

genxs configurationFile [destinationFolder]

توضیحات (DESCRIPTION)

ابزار genxs ابزاری برای تولید خواننده‌ها و نویسنده‌های سفارشی سریال‌سازی XML برای کلاس‌ها است.

شناسه configurationFile پرونده پیکربندی است که اطلاعات مختلفی را تعیین می‌کند؛ نظیر کلاسی که باید خواننده و نویسنده برای آن تولید شود، نام و فضای نام (namespace) کلاس‌های تولیدی، و مجموعه‌ای از قلاب‌ها (hooks) جهت اعمال. با استفاده از قلاب‌ها می‌توان رفتار سریالایزر را بدون نیاز به دستکاری فایل تولیدشده سفارشی‌سازی کرد، به طوری که در صورت تغییر کلاس مبدأ بتوان آن را مجدداً با اطمینان بازتولید نمود.

شناسه destinationFolder پوشه‌ای را تعیین می‌کند که فایل‌های تولیدی در آن ذخیره خواهند شد.

نکته: این ابزار صرفاً در محیط اجرای مونو (Mono) کار می‌کند، زیرا از برخی کلاس‌های داخلی بهره می‌برد که در سایر محیط‌های اجرایی موجود نیستند.

قالب فایل پیکربندی (CONFIGURATION FILE FORMAT)

پرونده پیکربندی یک سند XML مبتنی بر ساختار نحوی زیر است (علامت «?» به معنای اختیاری و «*» به معنای صفر یا چند بار تکرار است):

<configuration>
	<serializer class="name" assembly="name"> *
		<reader>name</reader> ?
		<writer>name</writer> ?
		<namespace>name</namespace> ?
		<outFileName>name</outFileName> ?
		<readerHooks> ?
			<hook ...> *
		</readerHooks>
		<writerHooks> ?
			<hook ...> *
		</writerHooks>
	</serializer>
</configuration>

یک پرونده پیکربندی می‌تواند شامل چندین عنصر «serializer» باشد که هر کدام کلاسی را برای تولید سریالایزر به همراه گزینه‌های مختلف تولید تعیین می‌کنند. کلاس مبدأ در ویژگی‌های زیر مشخص می‌شود:

*

class : نام کلاس (شامل فضای نام).

*

assembly : نام اسمبلی (می‌تواند شامل مسیر کامل باشد).

گزینه‌های تولید در عناصر فرزند تعیین می‌شوند:

*

reader : نام کلاس خواننده (reader).

*

noReader : در صورت تنظیم روی "true"، کلاس خواننده تولید نمی‌شود.

*

writer : نام کلاس نویسنده (writer).

*

baseSerializer : نام کلاس پایه سریالایزر XML (صرفاً در نسخه ۲.۰).

*

implementation : نام کلاس پیاده‌سازی سریالایزر (صرفاً در نسخه ۲.۰).

*

noWriter : در صورت تنظیم روی "true"، کلاس نویسنده تولید نمی‌شود.

*

namespace : فضای نام کلاس‌های خواننده و نویسنده.

*

generateAsInternal : در صورت تنظیم روی "true"، کلاس‌ها به صورت internal تولید می‌شوند.

*

outFileName : نام پرونده تولیدشده.

*

readerHooks : فهرستی از قلاب‌ها جهت اعمال بر روی خواننده.

*

writerHooks : فهرستی از قلاب‌ها جهت اعمال بر روی نویسنده.

تعیین قلاب‌ها (SPECIFYING HOOKS)

با استفاده از قلاب‌ها می‌توانید رفتار خواننده‌ها و نویسنده‌ها را سفارشی‌سازی کنید. نحوه نگارش قلاب مطابق گرامر زیر است:

<hook type="name">
	<select> ?
		<typeName>name</typeName> ?
		<typeAttribute>name</typeAttribute> *
		<typeMember>name</typeMember> ?
	</select>
	<replace>source code</replace> ?
	<insertBefore>source code</insertBefore> ?
	<insertAfter>source code</insertAfter> ?
</hook>

ویژگی «type» زمینه‌ای را که قلاب در آن اعمال می‌شود مشخص می‌کند و می‌تواند یکی از مقادیر زیر باشد:

*

attributes : قلاب در جایی که ویژگی‌ها سریال‌سازی یا بازنشانی می‌شوند اعمال می‌گردد.

*

elements : قلاب در جایی که عناصر سریال‌سازی یا بازنشانی می‌شوند اعمال می‌گردد.

*

unknownAttribute : قلاب در جایی که ویژگی‌های ناشناخته پردازش می‌شوند اعمال می‌گردد.

*

unknownElement : قلاب در جایی که عناصر ناشناخته پردازش می‌شوند اعمال می‌گردد.

*

member : قلاب در جایی که یک عضو سریال‌سازی یا بازنشانی می‌شود اعمال می‌گردد.

*

type : قلاب برای کل نوع (type) اعمال می‌شود.

عنصر «select» کلاس‌ها و اعضایی را که قلاب باید به آن‌ها اضافه شود تعیین می‌کند و می‌تواند شامل عناصر زیر باشد:

*

typeName : کلاسی با آن نام انتخاب خواهد شد (باید شامل فضای نام باشد).

*

typeAttribute : تمامی کلاس‌هایی که آن ویژگی به آن‌ها اعمال شده انتخاب می‌شوند (نام کامل کلاس ویژگی همراه با فضای نام). می‌توان چندین نام ویژگی را مشخص نمود.

*

typeMember : نام عضو کلاس که قلاب باید برای آن اضافه شود.

کد منبع قلاب را می‌توان با استفاده از هر یک از عناصر زیر تعیین کرد:

*

replace : کد منبع ارائه‌شده جایگزین کلیه عملیات سریال‌سازی/بازنشانی در زمینه قلاب خواهد شد.

*

insertBefore : کد منبع پیش از زمینه قلاب اضافه می‌شود.

*

insertAfter : کد منبع پس از زمینه قلاب اضافه می‌شود.

هنگام نوشتن کد برای یک قلاب می‌توانید از برخی متغیرهای ویژه که در طول فرآیند تولید کد تعریف می‌شوند استفاده کنید:

*

$TYPE: نام کلاس در حال تولید، بدون فضای نام.

*

$FULLTYPE: نام کامل کلاس در حال تولید، همراه با فضای نام.

*

$OBJECT: شیء در حال سریال‌سازی یا بازنشانی. هنگام استفاده از قلاب جایگزین خواننده از نوع "type"، کد قلاب باید شیء بازنشانی‌شده را به این متغیر انتساب دهد.

*

$ELEMENT: نام عنصر شیء در حال سریال‌سازی/بازنشانی.

*

$NAMESPACE: فضای نام عنصر شیء در حال سریال‌سازی/بازنشانی.

*

$MEMBER: نام عضو در حال سریال‌سازی/بازنشانی (تنها در زمینه "member" معتبر است).

نمونه‌های قلاب (HOOK EXAMPLES)

مثال زیر یک فراخوانی به متد Validate را پس از بازنشانی هر شیء اضافه می‌کند:

<hook type="type">
	<insertAfter>
		System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT);
	</insertAfter>
</hook>

این مثال کد مورد استفاده جهت بازنشانی کلاس XmlSchema را مشخص می‌کند:

<hook type="type">
	<select>
		<typeName>System.Xml.Schema.XmlSchema</typeName>
	</select>
	<replace>
		$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);
	</replace>
</hook>

این نمونه کد مورد استفاده برای خواندن نمونه‌های XmlSchema را مشخص می‌کند:

<hook type="type">
	<select>
		<typeName>System.Xml.Schema.XmlSchema</typeName>
	</select>
	<replace>$OBJECT.Write (Writer);</replace>
</hook>

با این دو قلاب، سریالایزر هنگام سریال‌سازی کلاس "MyClass" اطلاعاتی را چاپ خواهد کرد:

<hook type="type">
	<select>
		<typeName>MyNamespace.MyClass</typeName>
	</select>
	<insertBefore>Console.WriteLine ("Serializing MyClass");</insertBefore>
	<insertAfter>Console.WriteLine ("MyClass serialized");</insertAfter>
</hook>
<hook type="member">
	<select>
		<typeName>MyNamespace.MyClass</typeName>
	</select>
	<insertAfter>
		Console.WriteLine ("Serialized member $MEMBER");
	</insertAfter>
</hook>

این قلاب یک عنصر اضافی برای کلیه انواعی که دارای ویژگی سفارشی "MyAttribute" هستند می‌نویسد:

<hook type="elements">
	<select>
		<typeAttribute>MyNamespace.MyAttribute</typeAttribute>
	</select>
	<insertAfter>
		Writer.WriteStartElement ("privateData");
		Writer.WriteString ($OBJECT.PrivateData);
		Writer.WriteEndElement ();
	</insertAfter>
</hook>

نمونه پرونده پیکربندی (CONFIGURATION FILE EXAMPLE)

این پرونده پیکربندی مورد استفاده برای تولید سریالایزر ServiceDescription است:

<configuration>
	<serializer class="System.Web.Services.Description.ServiceDescription" assembly="System.Web.Services">
		<reader>ServiceDescriptionReaderBase</reader>
		<writer>ServiceDescriptionWriterBase</writer>
		<namespace>System.Web.Services.Description</namespace>
		<outFileName>ServiceDescriptionSerializerBase.cs</outFileName>
		<readerHooks>
			<hook type="unknownElement">
				<select>
					<typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
				</select>
				<replace>ServiceDescription.ReadExtension (Reader, $OBJECT);</replace>
			</hook>
			<hook type="type">
				<select>
					<typeName>System.Xml.Schema.XmlSchema</typeName>
				</select>
				<replace>$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);</replace>
			</hook>
		</readerHooks>
		<writerHooks>
			<hook type="elements">
				<select>
					<typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
				</select>
				<insertBefore>ServiceDescription.WriteExtensions (Writer, $OBJECT);</insertBefore>
			</hook>
			<hook type="type">
				<select>
					<typeName>System.Xml.Schema.XmlSchema</typeName>
				</select>
				<replace>$OBJECT.Write (Writer);</replace>
			</hook>
		</writerHooks>
	</serializer>
</configuration>

نویسندگان (AUTHORS)

Lluis Sanchez Gual (lluis@ximian.com)

مجوز (LICENSE)

ابزار GenXS تحت شرایط پروانه عمومی همگانی گنو (GNU GPL) منتشر شده است.

همچنین ببینید (SEE ALSO)

mono(1), mcs(1), sgen(1)