Microsoft Enterprise Library 5 - Documentation & Helpacross different layers of their applications. Unity Dependency Injection and Interception. Developers can use this to implement

MicrosoftEnterpriseLibrary5.0

WelcometoEnterpriseLibrary

WelcometoEnterpriseLibrary.ThefollowingsectionsofthisguidancedescribethewaysthatyoucanuseEnterpriseLibraryandtheindividualapplicationblocksinyourapplications.Thesectionsare:

WhatIsEnterpriseLibrary?AboutThisReleaseofEnterpriseLibraryDevelopingApplicationswithEnterpriseLibraryDesignofEnterpriseLibraryTheCachingApplicationBlock

TheCryptographyApplicationBlockTheDataAccessApplicationBlockTheExceptionHandlingApplicationBlockTheLoggingApplicationBlockThePolicyInjectionApplicationBlockTheSecurityApplicationBlockTheValidationApplicationBlockUnityDependencyInjectionandInterception

Toprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].

Copyright©2010byMicrosoftCorporation.Allrightsreserved.

http://codeplex.com/entlib/

mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Welcome to Enterprise Library'%0AEntLib50_417aa0a0-6a1b-4151-a512-e811afbab0ac%0APlease provide details of the error you have located...%0A


WhatIsEnterpriseLibrary?

EnterpriseLibraryconsistsofacollectionofapplicationblocksandcoreinfrastructure.Allofthesearereusablesoftwarecomponentsdesignedtoassistdeveloperswithcommonenterprisedevelopmentchallenges.

EnterpriseLibraryalsoprovidesmanyhighlyconfigurablefeaturesthatmakeitmucheasiertomanagerepetitivetasks,knownascrosscuttingconcerns,whichoccurinmanyplacesinyourapplications.Theseincludetaskssuchaslogging,validation,caching,exceptionmanagement,andmore.Inaddition,thedependencyinjectioncontaineritprovidescanhelptosimplifyanddecoupleyourdesigns,makethemmoretestableandunderstandable,andhelpyoutoproducemoreefficientdesignsandimplementationsofallkindsofapplications.

ThreeSimpleStepsforUsingEnterpriseLibrary

BenefitsofEnterpriseLibrary

GoalsforEnterpriseLibraryToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Is Enterprise Library?'%0AEntLib50_bf72fb56-b3ea-4a2d-91b8-488c6cac1fea%0APlease provide details of the error you have located...%0A


AboutThisReleaseofEnterpriseLibrary

ThissectioncontainsthefollowingtopicsthatwillhelpyoutounderstandthisreleaseofEnterpriseLibraryandhowyouuseitalongsideearlierversionsormigrateyourapplicationstothisversion.Thissectionincludesthefollowingtopics:

ChangesinThisReleaseTargetAudienceandSystemRequirementsContentsofEnterpriseLibraryMigrationandSide-by-SideExecutionRelatedpatterns&practicesLinksCopyrightandTermsofUse

HowtoUseThisGuidanceToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://www.codeplex.com/entlib/


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'About This Release of Enterprise Library'%0AEntLib50_bd523fec-ab56-483e-97f8-4f72019ac3a2%0APlease provide details of the error you have located...%0A


ChangesinThisRelease

EnterpriseLibrary5.0isanewreleaseoftheMicrosoftpatterns&practicesEnterpriseLibrary.Oneofthemajorchangesistheimplementationoffulldependencyinjectioncapabilitiesforinstantiatingandmanagingthelifetimeofobjects,whichmakescreationofEnterpriseLibraryobjectsconsistentacrosstheentirelibrary.EnterpriseLibrarycannowbeusedwithdifferentdependencyinjectioncontainers.Unityisthedefaultdependencyinjectioncontainer.ForalternativeDIcontainerconfigurationplug-insgotothepatterns&practices:EnterpriseLibraryContribWebsite.

Thisreleasealsoincludesadditionsinfunctionalitytoseveraloftheexistingapplicationblocks.Inaddition,thisreleasehasbeenadaptedtoworkwithbothMicrosoftVisualStudio®2008andMicrosoftVisualStudio2010;andwiththeMicrosoft.NETFrameworkversions4.0and3.5withServicePack1.

Thefollowingsectionsdiscusstheseandotherchanges:IntegrationofUnityandObjectBuilderBreakingChangesChangesThatAffectAllApplicationBlocksChangestotheConfigurationToolChangestotheCachingApplicationBlockChangestotheCryptographyApplicationBlockChangestotheDataAccessApplicationBlockChangestotheExceptionHandlingApplicationBlockChangestotheLoggingApplicationBlockChangestothePolicyInjectionApplicationBlockChangestotheSecurityApplicationBlockChangestotheValidationApplicationBlock

GotoCodePlexforinformationonKnownIssues.

http://www.codeplex.com/Wikipage?ProjectName=entlibcontrib

http://go.microsoft.com/fwlink/?LinkId=188428

IntegrationofUnityandObjectBuilder

http://msdn.microsoft.com/en-gb/library/dd203099.aspx

http://commonservicelocator.codeplex.com/

BreakingChanges


ChangesThatAffectAllApplicationBlocks



ChangestotheConfigurationTools

ChangestotheCachingApplicationBlock

ChangestotheCryptographyApplicationBlock

ChangestotheDataAccessApplicationBlock

ChangestotheExceptionHandlingApplicationBlock

ChangestotheLoggingApplicationBlock

ChangestothePolicyInjectionApplicationBlock

ChangestotheSecurityApplicationBlock

ChangestotheValidationApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Changes in This Release'%0AEntLib50_280c0073-fa13-478d-826a-89f4b683a029%0APlease provide details of the error you have located...%0A


TargetAudienceandSystemRequirements

Thisguidanceisintendedforsoftwarearchitectsandsoftwaredevelopers.Togetthegreatestbenefitfromthisguidance,youshouldhaveanunderstandingofthefollowingtechnologies:

MicrosoftVisualC#®orMicrosoftVisualBasic®.NETMicrosoft.NETFramework

SystemRequirementsandPrerequisitesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Target Audience and System Requirements'%0AEntLib50_597583b0-5770-4bed-bae9-54eb513ac71e%0APlease provide details of the error you have located...%0A


ContentsofEnterpriseLibrary

EnterpriseLibraryisacombinationofreusablecomponents,asupportinginfrastructure,andguidance.Itcontainsthefollowing:

Binaries.TheEnterpriseLibraryincludespre-compiled,strong-namedassembliesforallthesourcecode.Formoreinformation,seeDeployingEnterpriseLibrary.Sourcecode.TheEnterpriseLibraryincludesthesourcecodefortheapplicationblocks,thecoreinfrastructure,andtheconfigurationtool.Unittests.TheEnterpriseLibraryincludestheunitteststhatwerecreatedwhiletheapplicationblockswerebeingdeveloped.Formoreinformation,seeUnitTests.Documentation.EnterpriseLibraryincludesdocumentationthatcanbeviewedwiththeVisualStudioHelpsystem.ThedocumentationincludesguidanceabouthowtousetheEnterpriseLibraryandaclasslibraryreference.

AMigrationGuide,awiderangeofexamples,Hands-On-Labs,andotherlearningmaterialsareavailablefromtheEnterpriseLibrarycommunityWebsite.

ThefollowingtopicsdescribethecontentsofEnterpriseLibrarywithinthecontextoftheirfunction:

TheEnterpriseLibraryApplicationBlocksTheEnterpriseLibraryCoreTheEnterpriseLibraryConfigurationToolsTheInstanceCreationandDependencyInjectionMechanismUtilities,Tools,andGuidance

AdditionalfeaturesthatyoucanusewithEnterpriseLibraryareavailablefromtheEnterpriseLibraryCommunitySite.








mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Contents of Enterprise Library'%0AEntLib50_27dae947-45a7-4160-a7e3-18d2f9f93ee8%0APlease provide details of the error you have located...%0A


TheEnterpriseLibraryApplicationBlocks

TheEnterpriseLibraryapplicationblockshelptoaddressthecommonproblemsthatdevelopersfacefromoneprojecttothenext.TheyaredesignedtoencapsulatetheMicrosoftrecommendedpracticesfor.NETapplications.Inaddition,theycanbeaddedto.NETapplicationsquicklyandeasily.Forexample,theDataAccessApplicationBlockprovidesaccesstothemostfrequentlyusedfeaturesofADO.NETinsimple-to-useclasses,thusboostingdeveloperproductivity.Italsoaddressesscenariosnotdirectlysupportedbytheunderlyingclasslibraries.

Differentapplicationshavedifferentrequirements,andyouwillnotfindthateveryapplicationblockisusefulineveryapplicationthatyoubuild.Beforeusinganapplicationblock,youshouldhaveagoodunderstandingofyourapplicationrequirementsandofthescenariosthattheapplicationblockisdesignedtoaddress.

ThisreleaseofEnterpriseLibrarycontainsthefollowingapplicationblocks:TheCachingApplicationBlock.Developerscanusethisapplicationblocktoincorporatealocalcacheintheirapplications.TheCryptographyApplicationBlock.Developerscanusethisapplicationblocktoincorporatehashingandsymmetricencryptionintheirapplications.TheDataAccessApplicationBlock.Developerscanusethisapplicationblocktoincorporatestandarddatabasefunctionalityintheirapplications.TheExceptionHandlingApplicationBlock.Developersandpolicymakerscanusethisapplicationblocktocreateaconsistentstrategyforprocessingexceptionsthatoccurthroughoutthearchitecturallayersofenterpriseapplications.TheLoggingApplicationBlock.Developerscanusethisapplicationblocktoincludestandardloggingfunctionalityintheirapplicationsandsystemsadministratorscanusetheconfigurationtooltoadjustthegranularityofloggingatruntime.ThePolicyInjectionApplicationBlock.Thisblockcontainslegacycodeforbackwardscompatibilitywithexistingapplications.ThenewfunctionalityisavailablebyusingtheUnityinterceptionmechanismand

callhandlerslocatedintherelatedapplicationblockassemblies.TheSecurityApplicationBlock.Developerscanusethisapplicationblocktoincorporateauthorizationandsecuritycachingfunctionalityintheirapplications.TheValidationApplicationBlock.Developerscanusethisapplicationblocktocreatevalidationrulesforbusinessobjectsthatcanbeusedacrossdifferentlayersoftheirapplications.UnityDependencyInjectionandInterception.Developerscanusethistoimplementalightweight,extensibledependencyinjectioncontainerwithsupportforconstructor,property,andmethodcallinjection;andtocapturecallstotargetobjectsandaddadditionalfunctionalitytotheobject.

TheEnterpriseLibraryalsoincludesasetofcorefunctions,includingconfigurationandinstrumentation.Allotherapplicationblocksusethesefunctions.SeeTheEnterpriseLibraryCore.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Enterprise Library Application Blocks'%0AEntLib50_e58533a0-327b-41f7-ba56-52218284ac82%0APlease provide details of the error you have located...%0A


TheEnterpriseLibraryCore

EnterpriseLibrarycontainsasetofcorefeaturesthatintegratetheapplicationblockswiththeconfigurationsystem,supportalternativeconfigurationsystems,andprovidecommonutilitiesusedacrossalloftheapplicationblocks.ThefollowingaresomeexamplesofthecontentsoftheEnterpriseLibrarycore:

Run-timeconfigurationclassesandprovidersthatexposeconfigurationdatatothelibrary,theapplicationblocks,andusers'applicationsatruntimeCommonutilityfunctionsfortaskssuchasserialization,usedinmanyplacesthroughoutthelibraryandtheapplicationblocksandavailablefordeveloperstouseintheircodeInstrumentationfeaturesthatallowdevelopersandadministratorstomonitorthebehaviorandperformanceoftheapplicationblocksatruntimeDesign-timeconfigurationclassesthatsupporttheconfigurationtoolsandallowdeveloperstospecifyandpersistconfigurationinformationforthelibraryandtheapplicationblocks

FormoredetailsaboutthedesignoftheEnterpriseLibrarycorefeatures,seeTheEnterpriseLibraryCoreintheDesignofEnterpriseLibrarysectionofthisguidance.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Enterprise Library Core'%0AEntLib50_d95d61b8-8fdd-4be9-a2f7-698f43ef306c%0APlease provide details of the error you have located...%0A


TheEnterpriseLibraryConfigurationTools

Applicationblocksaredesignedtobeusedinavarietyofenterpriseapplicationdevelopmentscenarios.Thisdesignapproachenablesyoutoeasilyadaptanapplicationblocktomeettheneedsofyoursituation.Youdothiswithconfigurationsettings,whichyoucaneasilychangeusingtheconfigurationtools.Youcandefineconfigurationsettingsforanapplicationblock'scentralfunctionalityandforeachprovidertype.

YoucanuseVisualStudiotocreateandmodifyconfigurationfilesoryoucanusethestand-aloneEnterpriseLibraryconfigurationconsole.Collectively,theVisualStudiointegratedconfigurationeditorandthestand-aloneconfigurationconsolearereferredtoastheconfigurationtools.Bothoftheseconfigurationtoolshaveidenticalfunctionality.Withthesetools,youcanchangeandvalidateapplicationblocksettingswithoutmanuallyeditingtheXMLconfigurationfileswheretheyarestored.Theconfigurationtoolsdisplaythesesettingsandsupplydefaultvaluesthatyoucanchange.

Eachapplicationblockdefinespointsofextensibility,wheredeveloperscanincludetheirownimplementations(typically,theseareproviders)withspecificfunctionality.Forexample,youcanaddyourowncustomlogentryformatterstotheLoggingApplicationBlock.Thesecustomproviderscanbeinterchangedwiththeprovidersthataresuppliedwiththeapplicationblock.TheconfigurationconsoleletsyouselectthecustombackingstoreandwritesthisinformationtotheappropriateXMLconfigurationfile.Thismeansthattheapplicationwillusethecustomstorewithoutanycodechangesandwithoutbeingrecompiled.

TheVisualStudiointegratedconfigurationtoolisnamedtheconfigurationeditor.Theconfigurationeditorhasthesamefunctionalityasthestand-aloneconfigurationconsole,butitusestheVisualStudioPropertiesgridtodisplayanapplicationblock'spropertiesandusestheerrorslisttodisplayconfigurationerrors.

Thefollowingdescribessomeoftheactivitiestheconfigurationtoolshelpyouwith:

Youcanusetheconfigurationtoolstocreateandmodifystandard.NET

Framework<appSettings>sections.Formoreinformation,seeUsingtheappSettingsSection.Youcanusetheconfigurationtoolstotailoranapplicationblock'sconfigurationtoaparticularrun-timeenvironment.Formoreinformation,seeConfiguringaDeploymentEnvironment.Youcanusetheconfigurationtoolstoencryptanddecryptthedatacontainedinconfigurationsections.Formoreinformation,seeEncryptingConfigurationData.

Usingconfigurationsettingstoadaptanapplicationblocktoaparticularsituationhastwoadvantages:

Differentpeoplecanconfigurethecharacteristicsofanapplicationblockatdifferenttimesduringtheapplicationlifecycle.Forexample,adevelopercouldconfigureaprovidertoaccessaparticulardatabaseduringapplicationdevelopment,whileasystemadministratorcoulddecideduringdeploymenttoencryptthedatabaseconnectionstrings.Youcanchangetheapplicationblockconfigurationincrementallyforincreasinglycomplexsituations.Forexample,youcouldinitiallyconfigureanapplicationblocktousethedefaultsettingsandproviders.Asyourunderstandingofthescenariodeepens,youcanchangetheapplicationblockconfigurationwithoutmodifyingitscode,recompilingit,orredeployingit.

FormoreinformationonusingtheVisualStudioconfigurationeditorandtheconfigurationconsoleseeUsingtheConfigurationTools.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Enterprise Library Configuration Tools'%0AEntLib50_8f5a7290-726c-4dc0-88d3-a571d98aa15c%0APlease provide details of the error you have located...%0A


TheInstanceCreationandDependencyInjectionMechanism

EnterpriseLibraryincorporatesaneasy-to-usemechanismforcreatingandwiringinstancesofobjects(whichmaycontainotherdependentobjects),andmanagingtheirlifetimes.ThisfeatureistheUnitycontainerandthefollowingdesignpatternsareused:

DependencyInjectionInversionofControl(IoC)ServiceLocatorServiceContainerFactoryBuilder

UnityandEnterpriseLibraryToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Instance Creation and Dependency Injection Mechanism'%0AEntLib50_0a1f0644-e5ac-4d83-9097-c040956dd963%0APlease provide details of the error you have located...%0A


Utilities,Tools,andGuidance

TohelpdeveloperslearnhowtouseEnterpriseLibrary,andtomakesuretheygetoptimumresultsfromit,theinstallationofEnterpriseLibraryincludesthefollowingutilities,tools,andguidance:

BatchfilesthatbuildtheEnterpriseLibrarysourcecodeandcopytheassembliestotheappropriatelocations.Formoreinformation,seeBuildingEnterpriseLibraryfromtheSourceCode.UtilitiestoinstalltheinstrumentationrequiredbyEnterpriseLibrary.Formoreinformation,seeEnablingInstrumentation.

Inaddition,thesourcecodeforEnterpriseLibraryincludesVisualStudioprojectsandunitteststhatdeveloperscanusetoextendandmodifythelibraryandtheapplicationblocks.Developerscanmakesureapplicationsstillmeetthedesignrequirementsbyrunningtheunittestsandwritingnewtests.ForinformationabouttheunittestsincludedwithEnterpriseLibrary,seeUnitTests.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Utilities, Tools, and Guidance'%0AEntLib50_b8326834-e40e-41ca-9ce1-56d8e805aba7%0APlease provide details of the error you have located...%0A


MigrationandSide-by-SideExecution

Ingeneral,applicationsbuiltforEnterpriseLibraryfor.NETFramework2.0inJanuary2006andlaterwillfunctionwiththisreleaseofEnterpriseLibrarywithouttheneedforanycodechanges.Itwillbenecessarytoupdatethereferencestorefertothenewassembliesandtoupdatetheconfigurationfilestoreferencethecorrectversionoftheassemblies.ToreviewthefewbreakingchangesyoumayneedtoaddressgototheBreakingChangessection.

ThisversionofEnterpriseLibrarycanalsobeinstalledsidebysidewithearlierversionsofEnterpriseLibrary.YoucandeploynewapplicationswrittenforthisversionofEnterpriseLibraryalongwithapplicationswrittenforearlierversions.Inaddition,youcanchoosetomigrateexistingapplications,oneassemblyatatime,tothenewversion.

Ifyoudecidetouseside-by-sideexecution,youmustdeploythedifferentEnterpriseLibraryversionsindifferentdirectories.Inanyspecificdirectory,youcannotmixandmatchassembliesfromdifferentversions.Forexample,youcannothaveDataAccessApplicationBlockversion5.0inthesamedirectorywithCachingApplicationBlockversion4.0.

TheshippedprojectfilesusedataintheAssemblyInfo.csfiletobuildassembliesthathavedifferentversioninformation.Thisenablesyoutousestrongnamesandtoadddifferentversionstotheglobalassemblycacheforside-by-sideexecution.

PartialMigrationToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Migration and Side-by-Side Execution'%0AEntLib50_8d02083f-492c-4469-bb38-a3a82313d34c%0APlease provide details of the error you have located...%0A


Relatedpatterns&practicesLinks

ForinformationrelatedtoEnterpriseLibrary,andothertoolsandguidancefordesigningandbuildingapplications,seethepatterns&practicesWebsiteandguides:

Microsoftpatterns&practicesDeveloperCenterDeveloper'sGuidetoMicrosoftEnterpriseLibrary5MicrosoftApplicationArchitectureGuide,2ndEditionSolutionDevelopmentFundamentalspatterns&practicesSecurityGuidanceforApplicationsIndex.NETDataAccessArchitectureGuideImproving.NETApplicationPerformanceandScalabilityMonitoringin.NETDistributedApplicationDesignDeploying.NETFramework-basedApplications





http://msdn.microsoft.com/en-us/library/dd673617.aspx


http://msdn.microsoft.com/en-us/library/ms998408.aspx

http://msdn.microsoft.com/en-us/library/ee817654.aspx





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Related patterns & practices Links'%0AEntLib50_9528738a-253b-439e-8d67-7c6e25bb968d%0APlease provide details of the error you have located...%0A


CopyrightandTermsofUse

Thisdocumentisprovided"as-is".Informationandviewsexpressedinthisdocument,includingURLandotherInternetWebsitereferences,maychangewithoutnotice.Youbeartheriskofusingit.

Someexamplesdepictedhereinareprovidedforillustrationonlyandarefictitious.Norealassociationorconnectionisintendedorshouldbeinferred.

ThisdocumentdoesnotprovideyouwithanylegalrightstoanyintellectualpropertyinanyMicrosoftproduct.Youmaycopyandusethisdocumentforyourinternal,referencepurposes.

©2010Microsoft.Allrightsreserved.

Microsoft,Windows,WindowsServer,WindowsVista,VisualC#,VisualBasic,andVisualStudioaretrademarksoftheMicrosoftgroupofcompanies.Allothertrademarksarepropertyoftheirrespectiveowners.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Copyright and Terms of Use'%0AEntLib50_4b21425b-974d-4612-972a-903175c09dea%0APlease provide details of the error you have located...%0A


DevelopingApplicationswithEnterpriseLibrary

EnterpriseLibrarycanbeusefulinavarietyofsituations;thefollowingaresomeexamples:

EnterpriseLibraryprovidessufficientfunctionalitytosupportmanycommonscenariosthatenterprise-levelapplicationsmustaddress.EnterpriseLibrarycanserveasthebasisforacustomlibrary.Youcantakeadvantageoftheextensibilitypointsincorporatedineachapplicationblockandextendtheapplicationblockbysupplyingnewproviders.Youcanalsomodifythesourcecodefortheexistingapplicationblockstoincorporatenewfunctionality.Youcandevelopextensionsforexistingapplicationblocksandnewapplicationblocksyourself,oryoucanuseextensionsandapplicationblocksdevelopedbyothers.Finally,youcanaddnewapplicationblockstoEnterpriseLibrary.EnterpriseLibraryisdesignedsothatitsapplicationblockscanfunctionindependentlyofeachother.Youhavetoaddonlytheapplicationblocksthatyourapplicationwilluse;youdonothavetoaddtheentirelibrary.EnterpriseLibraryincludesthesourcecodefortheapplicationblocks.ThismeansyoucanmodifytheapplicationblockstomergeintoyourexistinglibraryoryoucanusepartsoftheEnterpriseLibrarysourcecodeinotherapplicationblocksorapplicationsthatyoubuild.EnterpriseLibraryincludescomprehensivedocumentation.Thismeansthatyoucanusethelibraryandthesourcecodeastoolsforlearningarchitectural,design,andcodingbestpractices.Awiderangeofexamples,Hands-On-Labs,andotherlearningmaterialsareavailablefromtheEnterpriseLibrarycommunityWebsite.

ThissectiondescribesthegeneralproceduresforworkingwithEnterpriseLibraryinyourapplications.Youcanfinddetailsofhowtouseeachoftheapplicationblocksintherelevantsectionforeach.Thissectionincludesthefollowingsetsofrelatedtopics:

ConfiguringEnterpriseLibrary.ThesetopicsdescribethebasicandmoreadvancedproceduresforconfiguringEnterpriseLibrary;includingusingtheconfigurationtools,sharingandmanagingconfigurationformultipleapplications,configuringEnterpriseLibraryprogrammatically,


encryptingconfigurationfiles,andenablingthebuilt-ininstrumentation.UsingEnterpriseLibraryinApplications.ThesetopicsdescribehowtoaddtheEnterpriseLibraryassembliestoyourprojects,importtherequirednamespaces,andcreateinstancesofEnterpriseLibraryobjectsthatexercisethefunctionalityoftheapplicationblocks.DeployingEnterpriseLibrary.ThesetopicsdiscusstheissuesthatyoushouldconsiderwhendeployingEnterpriseLibraryandapplicationsthatuseit.ThisincludesversioningandstrongnamingassembliesifyoumodifythesourcecodeforEnterpriseLibrary,andpointerstohelpyouuseEnterpriseLibraryinpartialtrustscenarios.AdministeringEnterpriseLibrary.ThistopicsummarizesthetechniquesavailabletoadministratorsandoperatorsforrunningmultipleversionsofEnterpriseLibrary,managingconfiguration,usingthebuilt-ininstrumentation,andintegratingwithsystemmanagementtools.ExtendingandModifyingEnterpriseLibrary.ThesetopicsprovideadviceonextendingandmodifyingEnterpriseLibrarybychangingthesourcecode,andinformationaboutcreatingcustomprovidersthatintegratewithEnterpriseLibraryandtheconfigurationtools.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Developing Applications with Enterprise Library'%0AEntLib50_f5ce41d8-3bed-406d-b3e0-5d06cf1be436%0APlease provide details of the error you have located...%0A


ConfiguringEnterpriseLibrary

ConfigurationinformationfortheEnterpriseLibraryapplicationblocksisstoredinXMLformat.Typically,theinformationexistsinanXMLfile.Bydefault,theXMLfilethatcontainstheinformationistheapplicationconfigurationfile.

YoucanmanuallyedittheXMLdata,buttheEnterpriseLibraryprovidestwoconfigurationtoolsthatgreatlysimplifythistask.Thesetoolsarethestand-aloneconfigurationconsoleandtheconfigurationeditorthatisintegratedwithVisualStudio®.IfyouchoosetomanuallyedittheXML,refertotheappropriateapplicationblockdocumentationforschemadetails.

Note:Whencreatingaconfigurationfileandaddingapplicationblocks,UsingtheConfigurationToolsprovidesalesserrorproneexperienceandistherecommendedprocess.EditingtheXMLinVisualStudiodoesnotenforcetheconfigurationfilehierarchyatalllevelsandcanresultininvalidXML.

Theconfigurationfilesarenotencrypted,theyareincleartext,bydefault.Aconfigurationfilemaycontainsensitiveinformationaboutconnectionstrings,userIDs,passwords,databaseservers,andcatalogs.Youshouldprotectthisinformationagainstunauthorizedread/writeoperationsbyusingencryptiontechniques.Toprovidesecuritytheymustbeencryptedorprotectedusingaccesscontrollists(ACLs).Itisrecommendedthattheconfigurationstorebeinthesametrustboundaryandthatdecryptingtheconfigurationisdoneinthesametrustboundaryaftertheconfigurationisread.Forinformationabouthowtoencryptconfigurationfiles,seeEncryptingConfigurationData.

Thissectionincludesthefollowingtopics:UsingtheConfigurationToolsAdvancedConfigurationScenariosUsingGroupPolicywithEnterpriseLibraryConfiguringaDeploymentEnvironmentUsingtheFluentConfigurationAPIUsingtheappSettingsSection

http://msdn.microsoft.com/en-us/library/aa374872(VS.85).aspx

UpdatingConfigurationSettingsatRunTimeEncryptingConfigurationDataEnablingInstrumentationSourceSchemaforEnterpriseLibraryCore




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring Enterprise Library'%0AEntLib50_05ae7aff-85e4-46b5-8401-c4df81a2ea00%0APlease provide details of the error you have located...%0A


UsingtheConfigurationTools

TheEnterpriseLibraryconfigurationtoolsaregraphicaltoolsthatallowyoutocreate,change,andvalidateapplicationblocksettingswithouthavingtomanuallyedittheXMLconfigurationfileswheretheyarestored.ThereisaconfigurationeditorthatintegrateswithVisualStudio2008,plusstandaloneversionsfordifferentoperatingsystemandMicrosoft®.NETFrameworkversionsthatyoucanlaunchfromwithinVisualStudiooropenfromyourStartmenu.

Thesetoolsdisplaytheavailableconfigurationsettings,thedefaultvaluesthatyoucanchange,andinformationaboutwhateachsettingmeans.

Thistopiccontainsthefollowingsections:LaunchingConfigurationEditorfromVisualStudioSettingtheVisualStudioConfigurationEditorastheDefaultEditorLaunchingtheStandaloneConfigurationToolUsingWizardsintheConfigurationToolUsingtheKeyboardwiththeConfigurationToolTheConfigurationTypeSelectorEnterpriseLibraryConfigurationSchemaBuildingtheConfigurationConsoleSpecifyingDifferentAssembliesConfigurationToolUsageNotes

LaunchingtheConfigurationEditorfromVisualStudio

SettingtheVisualStudioConfigurationEditorastheDefaultEditor

LaunchingtheStand-aloneConfigurationTool

UsingWizardsintheConfigurationTool

UsingtheKeyboardwiththeConfigurationTool

TheConfigurationTypeSelector

EnterpriseLibraryConfigurationSchema

BuildingtheConfigurationConsole

SpecifyingDifferentAssemblies

ConfigurationToolUsageNotesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the Configuration Tools'%0AEntLib50_cc9f653d-cf10-4bfa-a8a6-1795a25a6f9d%0APlease provide details of the error you have located...%0A


AdvancedConfigurationScenarios

TheEnterpriseLibrarystandaloneconfigurationconsoleandtheVisualStudiointegratedconfigurationeditorallowyoutosatisfyarangeofadvancedconfigurationscenariosbasedonexternalconfigurationsourcessuchasdiskfiles.Forexample,youcan:

Readconfigurationinformationfromawiderangeofsources.Enforcecommonconfigurationsettingsacrossmultipleapplications.Shareconfigurationsettingsbetweenapplications.Specifyacoresetofconfigurationsettingsthatapplicationscaninherit.Mergeconfigurationsettingsthatarestoredinasharedlocation.Createdifferentconfigurationsfordifferentdeploymentenvironments.

ThedefaultandsimplestscenarioforconfiguringEnterpriseLibraryistoconfigureyourapplicationusingtheconfigurationtoolwithoutaddingaConfigurationSourcessectionoranyconfigurationsources.ThisistheapproachdescribedinUsingtheConfigurationTools.

Whenyouusetheconfigurationtoolswithoutspecifyingaconfigurationsource,theydefaulttousingtheSystemConfigurationSourcetocreateasingleconfigurationfilethatcontainstheentireconfigurationfortheapplication.YourapplicationwillexpectthistobenamedApp.configfile(whichiscopiedto[exe-name].configwhenyoucompileyourapplication)orWeb.config(dependingonthetechnologyyouareusing),andwillreaditautomatically.

YoucanselectAddConfigurationSettingsontheBlocksmenutodisplaythesectionthatcontainsthedefaultSystemConfigurationSource.IfyouclickthechevronarrowtotherightoftheConfigurationSourcestitletoopenthesectionpropertiespaneyoucanseethattheSystemConfigurationSourceisalso,bydefault,specifiedastheSelectedSource—theconfigurationsourcetowhichtheconfigurationgeneratedbythetoolwillbewritten.WhenanapplicationthatusesEnterpriseLibraryreadstheconfiguration,itusesthesettingsspecifiedfortheselectedsource.

Byaddingadditionalconfigurationsources,youcanimplementmoreadvancedconfigurationscenarios.Thefollowingsectionsdescribethescenariosthatyoucanimplementusingtheconfigurationtools:

UsingaNon-defaultConfigurationStoreSharingtheSameConfigurationbetweenMultipleApplicationsManagingandEnforcingConfigurationforMultipleApplicationsSharingConfigurationSectionsacrossMultipleApplicationsApplyingaCommonConfigurationStructureforApplicationsManagingConfigurationinDifferentDeploymentEnvironments

Youcanalsochangethecontentsofaconfigurationfileprogrammatically,whichisusefulwhenworkingwithsharedconfigurationstoredasdiskfiles.Formoreinformation,seeUpdatingSharedConfigurationSettingsProgrammatically.Forlinkstorelatedtopicsandmoredetailsofhowtheconfigurationsystemworks,seeMoreInformationattheendofthistopic.

UsingaNon-defaultConfigurationStore

http://entlibcontrib.codeplex.com/

SharingtheSameConfigurationbetweenMultipleApplications

ManagingandEnforcingConfigurationforMultipleApplications

SharingConfigurationSectionsacrossMultipleApplications

ApplyingaCommonConfigurationStructureforApplications

ManagingConfigurationinDifferentDeploymentEnvironments

UpdatingSharedConfigurationSettingsProgrammatically

MoreInformationToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Advanced Configuration Scenarios'%0AEntLib50_d0f735b9-e96f-4dcd-a16e-abe2d87cc30a%0APlease provide details of the error you have located...%0A


UsingaNon-defaultConfigurationStore

TheEnterpriseLibraryconfigurationtoolsallowyoutospecifytheconfigurationsourcetobereadatruntimetoconfigureyourapplication.Youcanpointtoconfigurationfilesorothertypesofconfigurationsourcesfromwhichtoreadconfigurationinformation.Thistopicexplainshowtoaddanon-defaultconfigurationsourcetoyourconfiguration.ItusestheFile-basedConfigurationSource,butthesameapproachisusedwithotherconfigurationsources.

Toaddaconfigurationsource1. Onthetaskbar,clickStart,pointtoAllPrograms,pointtoMicrosoft

patterns&practices,pointtoEnterpriseLibrary5.0,pointtoEnterpriseLibraryConfiguration,andthenselecttheversionoftheconfigurationeditoryourequire.Alternatively,right-clickonaconfigurationfileinVisualStudioSolutionExplorerandclickEditEnterpriseLibraryV5Configuration.

2. SelectAddConfigurationSettingsontheBlocksmenutodisplaythesectionthatcontainstheconfigurationsources.

3. ClicktheSourcesplus-signicon,pointtoAddSources,andthenclickAddFile-basedConfigurationSource.

4. AnewsectionisaddedtotheSourcespanewiththedefaultnameofthetypeofconfigurationsourceyouadded,forexampleFile-basedConfigurationSource.Ifyouaddmorethanoneofthesameconfigurationsourcetype,thedefaultnamesincrementbyoneeachtime.

5. Setthepropertiesoftheconfigurationsource.Forexample,settheFilePathpropertybytypingthefilepathandnameofthefile,orby

clickingtheellipsisbutton(…)andnavigatingtothefileyouwanttouse.Thefilecanbelocatedonthelocalmachine,orinasharedlocationifyouwanttousethesameconfigurationformultipleapplicationsorapplicationlayers.

6. EdittheNamepropertyoftheconfigurationsourceifrequired.7. ClicktheConfigurationSourcespropertyexpanderchevrontoopen

thepropertiespaneforthesection.SettheSelectedSourcepropertybyselectingtheconfigurationsourceyouwanttouseforyourapplicationfromthedrop-downlist.

8. OntheFile,menuclickSaveorSaveAs.

Note:AQuickStartsamplenamedSqlConfigurationthatimplementsanexampleSQLConfigurationSourcetodemonstratehowyoucanstoreconfigurationinformationinadatabaseisavailablefromtheEnterpriseLibraryContribWebsite.ThisproviderusestheDataAccessApplicationBlocktoreadconfigurationsettingsfromaSQLServer©database.





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using a Non-default Configuration Store'%0AEntLib50_bb3cf811-6f61-450b-b9e5-b526f53b3ecc%0APlease provide details of the error you have located...%0A


SharingConfigurationSectionsacrossMultipleApplications

Youcanuseredirectiontoreadtheconfigurationforindividualapplicationblocks(individualconfigurationsections)fromasharedlocationorotherconfigurationsource.Thisenablesyoutousealocalapplicationconfigurationforsomeapplicationblocks,whilereadingandincludingthesharedsectionsconfiguration.Youcreatecompositeconfigurationslikethisbyspecifyingadditionalsourcesinyourapplicationconfigurationfile.Thecontentsoftheindividualsectionsintheconfigurationsourcecanbereadandincludedwiththecontentsofyourdefaultapplicationconfigurationfileatruntime.

ThefollowingprocedureexplainshowyoucanusetheconfigurationtoolstoredirectEnterpriseLibrarytoreadaspecificconfigurationsection'scontentfromaspecifiedsource.

Touseredirectiontoreadaconfigurationsectionfromasharedsource1. Onthetaskbar,clickStart,pointtoAllPrograms,pointtoMicrosoft

patterns&practices,pointtoEnterpriseLibrary5.0,pointtoEnterpriseLibraryConfiguration,andthenselecttheversionoftheconfigurationeditoryourequire.Alternatively,right-clickonaconfigurationfileinVisualStudioSolutionExplorerandclickEditEnterpriseLibraryV5Configuration.

2. OntheBlocksmenuclickAddConfigurationSettings.3. IntheSourcespaneclicktheplus-signicon,pointtoAddSourcesand

thenclickthetypeofconfigurationsourceyouwanttoaddtotheconfiguration.Thisistheconfigurationsourcetowhichyouwillredirectconfigurationsections.Inthisexample,weaddaFile-basedConfigurationSource.

4. IntheSourcescolumn,enterthedesiredFilePathpropertyforthenew

configurationsourcebytypingthepathandfilenameorbyclickingtheellipses(...)buttonandnavigatingtothefile.

5. YoucannowredirectsectionsfromyourlocalsourcetoanotherusingtheRedirectedSectionspane.ClicktheplussigniconintheRedirectedSectionscolumnandclickAddRedirectedSection.

6. InthenewRedirectedSectionthatisdisplayed,selecttheconfigurationsectionthatyouwanttoredirecttoasharedconfigurationsource.Afteryouselectthesection,thenameoftheredirectedsectionchangestoreflectthis.

7. Selecttheconfigurationsourcethatwillexposethesharedconfigurationsectionyouwanttouseinthedrop-downlistfortheConfigurationSourcepropertyoftheredirectedsection.Aconnectinglineappearsshowingwhichconfigurationsourcewillprovidetheinformationfortheredirectedsection.

8. ClickSaveorSaveAstosavetheconfiguration.

Note:IntheConfigurationTool,whenredirectedsectionsareusedwithaSelectedSourceotherthanSystemConfigurationSource,theredirectedsectionsconfigurationinformationwillstillbesavedtotheSystemConfigurationSource,whichisthefileopenedintheconfigurationtool.Toeditthecontentsofthesharedconfigurationsections,opentheconfigurationthatcontainsthemdirectly.

AnExampleoftheXMLGeneratedbyRedirectedSectionsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Sharing Configuration Sections across Multiple Applications'%0AEntLib50_4c09bfbf-a6ff-437d-ac7e-2738e55c9b96%0APlease provide details of the error you have located...%0A


ApplyingaCommonConfigurationStructureforApplications

Ifyouaddaconfigurationsourcetoyourapplicationconfigurationandspecifythatthisconfigurationsourceistheparentsource,EnterpriseLibrarywillreadthecontentsofthisconfigurationsourceandmergeanylocalconfigurationsettingsyouhavespecifiedwiththisparentconfiguration.Effectively,itinheritsthesharedconfigurationandthenappliesthelocalsettingstooverrideanythatoccurinbothconfigurations.Youcanusetheconfigurationtooltospecifyaparentconfigurationthatwillbeinherited.

Toinheritasharedconfigurationstructureandsettingsfromanotherconfigurationsource

1. Onthetaskbar,clickStart,pointtoAllPrograms,pointtoMicrosoftpatterns&practices,pointtoEnterpriseLibrary5.0,pointtoEnterpriseLibraryConfiguration,andthenselecttheversionoftheconfigurationeditoryourequire.Alternatively,right-clickonaconfigurationfileinVisualStudioSolutionExplorerandclickEditEnterpriseLibraryV5Configuration.

2. OntheBlocksmenuclickAddConfigurationSettings.3. IntheSourcespaneclicktheplus-signicon,pointtoAddSourcesand

thenclickthetypeofconfigurationsourceyouwanttoaddtotheconfiguration.Thisistheconfigurationsourcefromwhichyouwillinheritconfigurationinformation.Inthisexample,weaddaFile-basedConfigurationSource.

4. Setthepropertiesoftheconfigurationsourceyouadded.Forexample,enterthedesiredFilePathpropertyforthenewconfigurationsourcebytypingthepathandfilenameorbyclickingtheellipses(...)buttonandnavigatingtothefile.

5. ClicktheConfigurationSourcespropertyexpanderchevrontoopenthepropertiespaneforthesection.SettheParentSourcepropertytotheconfigurationsourcewhosesettingsyouwanttoinherit.

6. ClickSaveorSaveAsontheFilemenutosaveyourconfiguration.

Settingsintheinheritedconfigurationsourcewillapplytoyourapplicationunlessyouoverridethembyconfiguringthesamesettinginyourlocalconfiguration.Forinformationabouthowsettingsareinheritedandmerged,seeMergeRulesforInheritedConfiguration.

Toprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,pleasesendemailto


[email protected].


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Applying a Common Configuration Structure for Applications'%0AEntLib50_a1391fa6-3bd5-43f6-9d41-3f19ca61f1b5%0APlease provide details of the error you have located...%0A


MergeRulesforInheritedConfiguration

Whenyouspecifyaparentsourcefromwhichyouinheritsharedconfigurationinformation,allofthatconfigurationinformationisreadandthesettingsaremergedatrun-timeatthelevelofindividualsettingelements.Forexample,youcanaddexceptionhandlerstoanexistingpolicy,oraddapropertytoanelementinthelocalconfigurationthatdoesnotexistinthedefaultsettings.TheruntimemergebasicallybehaveslikealogicalOR.Iftheelementorpropertyisinoneoftheconfigurationfiles,itwillbepresentinthemergedconfiguration.

Ifanelementorpropertyispresentinbothsourceswhenyouinheritasection,theelementinthelocalconfiguration(thelocalsource)istheonepresentintheresultingmergedconfiguration.Inheritancecanonlybeoneleveldeep;youcannotdefineaparentsourceforaconfigurationsourcethatisitselfusedasaparentsource.Thispreventstheaccidentalcreationofcircularreferencesandendlessrecursion.

Note:Whenyouuseenvironmentaloverridestospecifydifferentconfigurationsfordifferentdeploymentenvironmentsinconjunctionwithsettingsinheritedfromaparentsource,themergerulesdescribedheredonotapplytotheinheritedconfigurationsettings.Themergedconfigurationisspecifiedbythecombinationofthecommonandthedelta(differences)configurationfilesthatyoumerge.

Whenyouuseredirectedsections,andanelementorpropertyispresentinbothsources,theelementfromthesharedconfiguration(thesourceyouredirectthesectionto)istheonepresentintheresultingmergedconfiguration.Localsettingsinaredirectedsectionareignored.Ifyouspecifyaparentsourceaswellasredirectedsections,themergebehaviorappliestotheredirectedsections.

Toavoidissueswhenyouusedifferenttoolstomanageyourconfiguration,youshouldavoidinheritingthestandard.NETconfigurationsectionsthatarealsousedbyEnterpriseLibrary,suchasappSettingsandconnectionStrings.

Whencreatingacompositeconfiguration,thereisahierarchytothecomponentsmergedintoyourEnterpriseLibraryconfigurationatruntime,asdescribedinAdditiveMergebelow.Inaddition,thereisahierarchyformergingofthecollectionsfromthespecifiedsources,describedinthesectionMergedCollectionsOrderlaterinthistopic.

AdditiveMerge

MergedCollectionsOrderToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Merge Rules for Inherited Configuration'%0AEntLib50_0211977e-2655-4b6e-aae5-5b42a74dd609%0APlease provide details of the error you have located...%0A


AbouttheConfigurationSystem

EnterpriseLibraryfirstlooksatthedefaultconfigurationfile(thecurrentapplicationdomainconfigurationfile).ThiswillbeeitheryourApp.configfile(whichiscopiedto[exe-name].configwhenyoucompileyourapplication)oryourWeb.configfile.Thisfilemaycontainaconfigurationsectionthatdefinesadditionalconfigurationsources.Thecoreconfigurationclassesthatsupportreadingconfigurationinformationfirsttrytoreadtherequestedconfigurationsectionfromtheconfiguredsourcelocation.

TheenterpriseLibrary.ConfigurationSourcesectionintheconfigurationfilecarriestheselectedSourceattribute,whichspecifiestheconfigurationsourcethattheapplicationshoulduse.The<enterpriseLibrary.ConfigurationSource>sectionisretrievedfromthecurrentapplicationdomain'sconfigurationfile,andEnterpriseLibraryusestheconfigurationinformationexposedbytheconfigurationsourcespecifiedbytheselectedSourceattribute.

ThesourcedefinedbytheselectedSourceattributecouldbeanyofthefollowingsources:

ASystemConfigurationSource,whichreadsfromtheapplication'sconfigurationfile.

AFile-basedConfigurationSource,whichreadsfromanarbitraryfile.AManageableConfigurationSource,whichreadsfromanarbitraryfileandappliesgrouppolicyoverrides,oranycustomconfigurationsource.ThesampleSQLConfigurationSourceavailablefromtheEnterpriseLibraryContribProjectWebsite,whichreadsconfigurationdatafromadatabase.AcustomconfigurationsourcethatyoucreateandaddtoEnterpriseLibrary.

Ifthereisno<enterpriseLibrary.ConfigurationSource>sectionintheconfigurationfile,aninstanceoftheSystemConfigurationSourceclassisusedbydefaultandbecomestheapplicationconfigurationsource.

Note:ConfigurationsourcesareanextensibilitypointinEnterpriseLibrary.

ThefollowingXMLfragmentshowsaconfigurationsectionthatspecifiesEnterpriseLibraryshouldreadconfigurationinformationusingtheFileConfigurationSource.XML

<enterpriseLibrary.ConfigurationSourceselectedSource="fileSource">

<sources>

<addname="fileSource"

type="Microsoft.Practices.EnterpriseLibrary.Common.Configuration.FileConfigurationSource,

Microsoft.Practices.EnterpriseLibrary.Common"

filePath="test.exe.config"/>

<addname="systemSource"

type="Microsoft.Practices.EnterpriseLibrary.Common.Configuration.SystemConfigurationSource,

Microsoft.Practices.EnterpriseLibrary.Common"/>

</sources>

</enterpriseLibrary.ConfigurationSource>


RedirectionandInheritanceConfigurationPropertyandAttributeSettings

SavedConfigurationSettingsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'About the Configuration System'%0AEntLib50_d294bdc2-2c9d-4358-96ac-bff4017afd0f%0APlease provide details of the error you have located...%0A


UsingGroupPolicywithEnterpriseLibrary

GroupPolicyprovidesacentralizedone-to-manymanagementcapabilityforWindowsthatallowsadministratorstodefinesettingsthatapplytoagroupofcomputers,systems,services,orapplications.GroupPolicyreliesontheActiveDirectory®servicetomanagethesettingsappliedatruntimetomembersoftheActiveDirectoryforest,domain,orsubgroup.FormoreinformationaboutGroupPolicy,seeGroupPolicyonMSDN.

EnterpriseLibraryincludesamanageableconfigurationsource.ThisallowsyoutouseGroupPolicytomanageanEnterpriseLibraryapplication.Youdonotneedtowriteanyapplicationcodetousethesefeatures.ThistopicprovidesinformationaboutthefollowingtasksforusingGroupPolicy:

AddingaManageableConfigurationSourceGeneratingandInstallingGroupPolicyTemplatesTroubleshootingGroupPolicy

http://msdn2.microsoft.com/en-us/library/aa374177.aspx

AddingaManageableConfigurationSource

GeneratingandInstallingGroupPolicyTemplates

http://www.microsoft.com/downloads/details.aspx?FamilyID=7d2f6ad7-656b-4313-a005-4e344e43997d&displaylang=en

http://www.microsoft.com/downloads/details.aspx?FamilyId=9FF6E897-23CE-4A36-B7FC-D52065DE9960&displaylang=en

http://download.microsoft.com/download/a/d/b/adb5177d-01a7-4f04-bfcc-cb7cea8b5bb7/gpmc.msi

TroubleshootingGroupPolicy

AdministratorEntersInvalidValues

ApplicationIsModifiedWithoutGeneratingNewGroupPolicyTemplate

PoliciesConflicttoProduceInvalidConfiguration

OtherErrorsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Group Policy with Enterprise Library'%0AEntLib50_6cd834dd-557c-492a-9bc6-7a653c6ac367%0APlease provide details of the error you have located...%0A


ConfiguringaDeploymentEnvironment

Youcanusetheconfigurationtoolsatdesigntimetocustomizetherun-timesettingsofyourconfigurationtosuitaparticulardeploymentenvironment.Thisfeatureisusefulifyouhavemultipleenvironmentsthatsharethesamebasicconfigurationbutrequiredifferentpropertysettings.Forexample,youmayhaveadevelopmentenvironmentthatusesoneconnectionstringfortheDataAccessApplicationBlockandatestenvironmentthatusesadifferentone.

Everyenvironmentyouconfiguremaintainsitsownenvironmentdeltafile(usingthefilenameextension.dconfig),whichisupdatedafteryousavetheconfiguration.Thisenvironmentdeltafilecontainsthedifferencesbetweenthisenvironmentandthestandardenvironment,plussomeadditionalmetadataformergingthedifferencesintoanewcompleteconfigurationfilethatyoucandeploy.Themainadvantageisthatyoucandistributeanenvironmentdeltafileseparatelyfromtheoriginalconfigurationfileandallowmanagementbyusersoradministratorswhohaveaccesstoallthepasswords,servernames,andotherdetailsofthatenvironment.

Therefore,insteadofmaintainingmultipleconfigurationfilesorhavingtochangeafilemanuallyorprogrammatically,youcancreateabaseconfigurationfile(.config)andanenvironmentdeltafilethatcontainsthedifferences(.dconfig).

Youcanuseenvironmentalpropertyoverridestooverridespecificpropertiesforablockandforthepropertiesofthechildelementsforablock,andthencreateadeploymentenvironmentbysavingtheconfigurationdelta.Thenyoucanexportthemergedconfigurationfileandcopyordeployittoproduction.

Thelifetimeofthemainconfigurationandthelifetimeoftheenvironmentaloverridesarelinkedonlythroughthestructureofthefiles.Thefollowingoperationscanbeperformedonenvironmentdeltafiles:

File|Save:Savingthemainconfigurationalsosavesanyrelatedenvironments.Theenvironment.dconfigfileissavedusingthepathspecifiedintheEnvironmentDeltaFilepropertyoftheenvironmentoverride.File|SaveAs:Specifyinganewpathornameonlyaffectsthemain

configurationfile.YoumustchangethepathandnamespecifiedintheEnvironmentDeltaFilepropertyoftheenvironmentoverridetochangetheenvironmentnameandpath.File|New:Creatinganewconfigurationclearstheexistingconfigurationandallopenenvironments,createsanewemptyconfigurationfile,andclearsthevalidationresults.Youarepromptedtosavethefilebeingclearedifithasanychanges.Validation:Youcansaveconfigurationandenvironmentfilesonlyifallfilesarevalid.Eitherallaresavedornonearesaved.

Toopenorcreateaconfigurationfileinordertocreateadeploymentenvironment

1. ClickonOpenintheFilemenutoopenanexisting.configfile,orclickNewontheFilemenutocreateanewfile,andthenaddtheappropriatelyconfiguredapplicationblocksintheconfigurationtool.

2. Browsetotheconfigurationfileyouwantorthelocationwhereyouwanttosavethenewfile.

3. Selectaconfigurationfileandviewtheconfiguredapplicationblocks.

Tocustomizeablock'spropertiesforaruntimeenvironment1. OntheEnvironmentsmenu,clickNewEnvironmenttoopenanew

environmentconfigurationfile.Youmusthaveanenvironmentopeninorderforthepropertyoverridestobedisplayed.

2. ClicktheEnvironmentpropertyexpanderchevrontoopenorclosetheenvironmentpropertieseditpane.Note:

Youcanhavemultipleenvironmentconfigurationfilesopensimultaneously.Eachisdisplayedbyname.

3. Intheeditpane,settheproperties.TheEnvironmentDeltaFilepropertyisthenameofthedeltafile.Ifyouwanttoencryptthefile,settheProtectionProviderpropertybyselectingaproviderfromthedrop-downlist.TheEnvironmentConfigurationFilepropertyisthenameofthemergedconfigurationfile.TheEnvironmentNamepropertyisthenameoftheenvironment.

4. Repeatthepreviousstepsforeachenvironmentyouwanttocreate.5. Tocustomizeablock'spropertiesforthisenvironment,addthe

applicationblocktotheconfiguration.OpentheBlocksmenuandselecttheblockyourequirebyclickingonitssettings;forexample,AddLoggingSettings.

6. Clicktheblockspropertiesexpanderarrowtoviewthelistofproperties.IntheOverrideson[environmentname]drop-downbox,clickOverridePropertiestoenablesettingtheblock'spropertiesforthisenvironment.

Note:Ifyourenameanenvironment,theupdatednamemaynotbedisplayedintheOverrideson[environmentname]property.However,itwillbeshownthenexttimeyouopentheconfigurationinthetool.

7. Clicktheexpanderarrowontheleftofthenamedenvironmentlistedundertheblock'sproperties,inthisscreenshottotheleftofOverridesonTestPlatform,todisplaythepropertiesforthatnamedenvironment.Youcanthenuseeachpropertydrop-downeditboxtoeditthepropertiesappropriatelyforyourrequirements.

8. Repeatsteps4,5and6foreachblockyouwanttocustomize.

Note:Theconfigurationtoolallowsyoutoaddmorethanoneadditionalenvironment.Eachconfigureditemthendisplaysasetofpropertiesforthebaseconfigurationfileandasetofpropertiesspecifictoeachofthenamedenvironments(withtheexceptionofpropertiesthatcannotbeoverridden).Thisenablesyoutoeditthebaseconfigurationfilepropertiesorthedeltafilepropertiesforaspecificnamedenvironment.

Tocustomizeablock'schildelementpropertiesforarun-timeenvironment1. Clickonthechildexpanderarrowtotheleftoftheblockname

—LoggingSettingsinthisexample—todisplaythechildelementsiftheyarenotalreadyvisible.

2. Ineachofthechildelementsthatyouwanttoconfigurefordifferent

environments,clickonthepropertyexpanderfortheenvironmentyouwanttoedit—OverridesonTestPlatforminthisexample.

3. SettheOverrideson[environmentname]propertytoOverrideProperties,andtheneditthepropertiesyouwanttooverrideforthatenvironment.ThisscreenshotshowshowyoucanspecifydifferentpropertyvaluesforaLoggingblockcategoryfilterandatargetlistenerindifferentenvironments.

Tosaveaconfiguration(.config)fileandadeltaenvironment(.dconfig)file1. SelectSaveorSaveAsontheFilemenutosaveboththenamed

environmentconfigurationfileandthedeltafile;ifeitherfilenameisblankyouwillbepromptedtoselectapathandfilename.

CopyCode

2. ClickSave.Theconfigurationfileissavedandyouarepromptedforapathandnametosavethedeltaenvironmentfile.

3. ClickSaveAsandyouarepromptedfirstforapathandnametosavetheconfigurationfile.Thenyouarepromptedforapathandnametosavethedeltaenvironmentfile.

Tocreateamergedenvironmentconfigurationfile1. Right-clickonthenamedEnvironmentforwhichyouwanttocreatea

mergeddeploymentconfigurationfile,thenclickExportMergedEnvironmentConfigurationFile.

2. Tosavejustthedifferencesbetweenthemainandanenvironmentoverrideconfiguration,clickSaveEnvironmentDeltaFile.

Youcanalsomergeyourmainconfigurationfileandyourenvironmentdeltafilefromthecommandline.Thisisusefulifyouwanttousebuildscriptsorautomatedeployment.Tomergetheconfigurationfiles,youmustprovideboththemainconfigurationfileandtheenvironmentdeltafileinyourcommand.Thefollowingcommandshowsthesyntax.

MergeConfiguration.execonfigFiledeltaFile[mergedFile]

Theparametersarethefollowing:configFile.Thisisthemainconfigurationfile(.config).Itismergedwiththeenvironmentdeltafile.deltaFile.Thisistheenvironmentdeltafile(.dconfig).Itcontainstheinformationthatismergedintothemainconfigurationfile.mergedFile.Thisistheoutputfile.ThisfileresultsfrommergingconfigFilewithdeltaFile.IfyoudonotspecifythemergedFile,thefilenamestoredindeltaFileisused.

Note:Theenvironmentdeltafiles(.dconfig)youcreatemustbereloadedeachtimeyoucloseandreopentheconfigurationfile.

Toreloadanenvironmentdeltaconfigurationfile1. StarttheEnterpriseLibraryconfigurationconsoleoropenthe

configurationfileintheVisualStudioconfigurationeditor.Formore

informationontheEnterpriseLibraryconfigurationconsoleseeUsingtheConfigurationTools.

2. OntheFilemenu,clickOpen.3. IntheOpendialogbox,browsetoandselecttheapplication.configfile

youwanttoreload.4. IntheEnterpriseLibraryconfigurationtool,left-clickEnvironments,

andthenclickOpenDeltaFile.5. IntheOpendialogbox,selecttheenvironmentdeltaconfiguration

(.dconfig)fileyouwanttoreload,andthenclicktheOpenbutton.6. SavethechangesthroughtheFilemenuortheright-clickshortcut

menuontheenvironmentitem,asdescribedinthepreviousprocedure.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring a Deployment Environment'%0AEntLib50_91c6d2cf-d3f1-4c96-a972-4d56c71c3924%0APlease provide details of the error you have located...%0A


UsingtheFluentConfigurationAPI

ItispossibletoprogrammaticallymanipulatethedefaultconfigurationclassesusedbyEnterpriseLibraryforthecore,instrumentation,andalloftheapplicationblocks.ThefluentinterfaceexposedbyEnterpriseLibraryisdesignedtofacilitatethisprocess.ThefluentinterfacecanbeusedforalloftheconfigurablefeaturesofinstrumentationandforalloftheEnterpriseLibraryapplicationblockswiththeexceptionoftheValidationandPolicyInjectionApplicationBlocks.

UsingthefluentconfigurationAPI,youcan:CreateconfigurationsourcestopasstoEnterpriseLibraryobjectsthatyoucreateinyourapplications.Createconfigurationsourcesforentiresectionsoftheconfiguration,suchasfortheExceptionHandlingApplicationBlockortheLoggingApplicationBlock.CreatethecompleteconfigurationforEnterpriseLibraryforanapplication.Createdifferentenvironment-specificconfigurationsforsectionsorforentireapplications;thismakesiteasiertodeployanapplicationtodifferentrun-timeenvironments.Modifytheconfigurationatruntime;perhapstotakeintoaccountexternalfactorsorchangestotheenvironment.

Effectively,thefluentconfigurationAPIallowsyoutospecifyasetofconfigurationsectionsprogrammaticallyand,ifrequired,mergethemwithotherconfigurationsettingsspecifiedinothersourcessuchasafileconfigurationsource.Italsoallowsyoutoprogrammaticallydefineabaseconfigurationthatcanbechangedfromanothersource,suchasafileconfigurationsource,whichprovidestheabilitytooverridepartsofthebaseconfiguration.

WorkingWiththeFluentConfigurationAPIEnterpriseLibraryprovidestheConfigurationSourceBuilderclassthatactsasthebasisforcreatingconfigurationsources.Eachoftheblocks,andthecoreandinstrumentationfeaturesofEnterpriseLibrary,providesextensionstothisclassthatexposeafluentinterfaceandmakeiteasytocreateconfigurationsources.

ThegeneralapproachistocreateaninstanceoftheConfigurationSourceBuilderclassandthenspecifythesectionyouwanttoconfigure.Theextensionsforeachconfigurationsectionexposeintuitivemethodsthatallowyoutoaddtheappropriatepolicies,providers,orothertypesofextensionstotheconfigurationandspecifytherequiredconfigurationsettingsforeachone.InVisualStudio,theIntelliSense®featurewillhelpyoutolocateandusetheindividualmethodsavailableforeachconfigurationextension.Forexample,youcanconfigureinstrumentationforaconfigurationsourceusingthefollowingcode.C#

varbuilder=newConfigurationSourceBuilder();

builder.ConfigureInstrumentation()

.ForApplicationInstance("MyApp")

.EnableLogging()

.EnablePerformanceCounters();

varconfigSource=newDictionaryConfigurationSource();

builder.UpdateConfigurationWithReplace(configSource);

EnterpriseLibraryContainer.Current

=EnterpriseLibraryContainer.CreateDefaultContainer(configSource);

VisualBasic

Dimbuilder=NewConfigurationSourceBuilder()

builder.ConfigureInstrumentation()_

.ForApplicationInstance("MyApp")_

.EnableLogging()_

.EnablePerformanceCounters()_

DimconfigSource=NewDictionaryConfigurationSource()

builder.UpdateConfigurationWithReplace(configSource)

EnterpriseLibraryContainer.Current_

=EnterpriseLibraryContainer.CreateDefaultContainer(configSource)

Thefinallineinthiscodecreatesanewcontainerandassignstheconfigurationtoit.EnterpriseLibrarywillusethisconfigurationtoresolvetheobjectsitrequires.YoucanalsousethemethodsoftheIServiceLocatorinterfacetoobtaininstancesofEnterpriseLibraryobjectsondemandinyourcodebyaccessingtheIServiceLocatorimplementationthroughtheEnterpriseLibraryContainer.Currentproperty.

TheAPIalsoprovidesmethodsthatallowyoutocheckifaspecificsectionalreadyexistsintheconfiguration,andaddnewsectionstotheconfiguration.Forperformancereasons,thefluentconfigurationAPIdoesnotperformfullvaliditycheckingofthesettingsyouspecify.Itdoescheckfornullvalues,however.Toobtainfullvaliditychecking,youcanusethegraphicalconfigurationtoolstosetupandverifyyourconfiguration,andthentranslateitintocallstotheconfigurationAPI.

AllconfigurationsourceclassesimplementtheIConfigurationSourceinterface.Thisinterfaceallowsyourapplicationcodetosubscribetonotificationsofconfigurationchanges.Formoreinformation,seeUpdatingConfigurationSettingsatRunTime.Bydefault,inEnterpriseLibrary,onlytheLoggingApplicationBlockregisterstoreceivenotificationsofconfigurationchanges.

ThefollowingexamplesshowhowyoucanconfiguretheotherblocksinEnterpriseLibraryusingthefluentAPI:

TheCachingApplicationBlockTheCryptographyApplicationBlockTheDataAccessApplicationBlockTheExceptionHandlingBlockTheLoggingApplicationBlockTheSecurityApplicationBlock

TheCachingApplicationBlock

TheCryptographyApplicationBlock

TheDataAccessApplicationBlock

TheExceptionHandlingBlock

TheLoggingApplicationBlock

TheSecurityApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the Fluent Configuration API'%0AEntLib50_d935824f-a38b-4a3d-8a86-76d279a6e761%0APlease provide details of the error you have located...%0A


UsingtheappSettingsSection

YoucanusetheconfigurationtoolstocreateandmodifyMicrosoft.NETFramework<appSettings>sections.Notethatthe<appSettings>sectionsmustbeincludedinasinglefile;theyshouldnotbedistributedacrossmultiplefiles.ExamplesoffilesthatyoucannoteditincludetheMachine.configfileand<appSettings>sectionsthatincludetheoptionalfileattributethatspecifiesarelativepathtoanexternalconfigurationfile.

Configurean<appSettings>SectionUsingtheConfigurationTool

Configurean<appSettings>SectionbyEditingtheXMLToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the appSettings Section'%0AEntLib50_eaf61879-2a9d-4f53-9c58-d5c6ea3c9a77%0APlease provide details of the error you have located...%0A


UpdatingConfigurationSettingsatRunTime

ThedefaultconfigurationsystemincludedintheEnterpriseLibraryCoreis,withoneexception,read-only.Whenusingapplicationconfigurationfiles(App.configandWeb.config),updatestothesefilesdonotaffectexistinginstancesofobjects.However,newinstancescreatedafterchangesaremadetotheconfigurationfilewillreflectthesechanges.InWindowsFormsapplications,youcanrestarttheapplicationtocauseittoreadtheallofthenewconfigurationinformation.WebForms(ASP.NET)applicationswilldetectandreloadtheconfigurationinformation,butthestandardbehaviorofASP.NETcausestheapplicationtorestartwhenyouedittheconfigurationfile,whichcausesallstatetobelostfortheapplication.

TheoneexceptiontothisistheLoggingApplicationBlock,whichisabletodetectconfigurationchangesandreloadtheconfigurationwithoutrestartingtheapplication.ThisworksforWebFormsandWindowsFormsapplications,thoughitwillstillautomaticallytriggertheapplicationtorestartforWebFormsapplications.Thismeansthatyoucannotrelyonmaintenanceofin-processsessionstateinASP.NETapplicationswhenyouchangetheconfigurationfile.

DetectingConfigurationChangesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Updating Configuration Settings at Run Time'%0AEntLib50_1b2fd1e5-51a5-4f55-b0eb-cc830ca93b21%0APlease provide details of the error you have located...%0A


EncryptingConfigurationData

Youcanencryptanddecryptthedatainaconfigurationfile'sconfigurationsections.Aconfigurationsectioncontainstheconfigurationinformationforanapplicationblock.TheconfigurationtoolallowsyoutoselectfromtheencryptionprovidersthatareincludedintheMachine.configfile.Typically,thesearetheDataProtectionConfigurationProvider,whichusestheWindowsdataprotectionAPI(DPAPI),andtheRsaProtectedConfigurationProvider,whichusesRSA.

Iftheencryptedconfigurationfileisgoingtobeononlyasingleserver,youcanusetheDataProtectionConfigurationProvider.IfyouwanttodeploythesameencryptedconfigurationfileonmultipleserversinaWebfarm,youshouldusetheRsaProtectedConfigurationProvider.ThisprovidermakesiteasyforyouencryptthedataononeservercomputerandthenexporttheRSAprivatekeyneededtodecryptthedata.Youcanthendeploytheconfigurationfileandtheexportedkeytothetargetservers,andthenre-importthekeys.

TheuseraccountusedforencryptingthefilewhenusingtheRsaProtectedConfigurationProvidermusthavetheappropriateminimalpermissions,whichmustincludereadpermissionsontheNetFrameworkConfigurationKeykeycontainer,inordertoencryptanddecryptsectionswhenusingtheEnterpriseLibraryconfigurationtools.Bydefault,thisincludesonlyadministrativeaccounts.

Theappropriateminimalpermissions,whichmustincludereadpermissions,arealsorequiredforruntimeandconfigurationmergesperformedwhenusingtheconfigurationtoolsandworkingwithconfigurationsectionsthathavebeenencryptedbyusingtheRsaProtectedConfigurationProvider.

FormoreinformationseeCreatingandExportinganRSAKeyContaineronMSDN.

Note:Wheneveryouchangesecuritysettingsandpermissions,besurethatyouareawareofanysecurityrisksraisedbygivingelevatedpermissions.

http://msdn.microsoft.com/en-us/library/2w117ede.aspx

Toencryptaconfigurationsection1. OpenoneoftheEnterpriseLibraryconfigurationtools.2. Openanexistingconfigurationfileorcreateanewone.3. Clickthechevronarrowattherightofnameoftheapplicationblock

whoseconfigurationinformationyouwanttoencrypt.4. InthePropertiespane,clickthedrop-downlistfortheProtection

Providerproperty.5. SelecteitherDataProtectionConfigurationProvideror

RsaProtectedConfigurationProvider.

Allthesettingsfortheproviders,suchaswherekeysarestored,arealsointheMachine.configfile.Youcannotchangethisfilewithaconfigurationtool.Instead,youmustmodifythefileusingatexteditor.

Todecryptaconfigurationfile,simplyopenitintheconfigurationtool.Thefileisautomaticallydecrypted.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Encrypting Configuration Data'%0AEntLib50_f48f5196-4e77-461b-b700-5fa6daf41d35%0APlease provide details of the error you have located...%0A


EnablingInstrumentation

Theterminstrumentationreferstoasystem'sbuilt-inabilitytomonitorormeasureperformanceandtodiagnoseerrors.EnterpriseLibraryincorporatesthefollowinginstrumentationinthemajorityoftheapplicationblocks:

Eventlogs.Theapplicationblocksinformusersofkeyevents,suchaserrorsorwarnings.Performancecounters.Theapplicationblocksrecordkeymetrics—suchasthenumberofcriticaleventsthatoccurpersecondortheaveragetimeittakestocompletekeytasks—bywritingtotheMicrosoftWindows®operatingsystemperformancecounters.

FordetailsofthedesignoftheEnterpriseLibraryinstrumentation,seeInstrumentation.

EnablingandDisablingInstrumentation




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Enabling Instrumentation'%0AEntLib50_f15ecbcb-4dd8-44dc-b41d-8760b7d3805e%0APlease provide details of the error you have located...%0A


SourceSchemaforEnterpriseLibraryCore

TheEnterpriseLibraryCoreprovidesservices,suchasinstrumentationandconfiguration,andallEnterpriseLibraryapplicationblocksexceptforUnityaredependentonthecore.ThecorelibraryfunctionalityiscontainedintheassemblyMicrosoft.Practices.EnterpriseLibrary.Common.dll.

TherearetwoconfigurationsectionsassociatedwiththeEnterpriseLibraryCore.TheyaretheinstrumentationConfigurationsectionandtheenterpriseLibrary.ConfigurationSourcesection.Thesesectionsdefinewhichtypesofinstrumentationareenabledintheapplication(ifany),andwhichconfigurationsourceshouldbeusedtoaccessconfigurationinformationwithintheapplication.ThefollowingXMLcodeshowstheconfigurationsectiondeclarationsthatdefinethelocationsoftheseconfigurationsections.Thesedeclarationsshouldbedefinedwithinthe<configSections>sectionoftheapplicationconfigurationfile.XML

<configSections>

<sectionname="instrumentationConfiguration"

type="Microsoft.Practices.EnterpriseLibrary.Common.Instrumentation.Configuration.InstrumentationConfigurationSection,


<sectionname="enterpriseLibrary.ConfigurationSource"

type="Microsoft.Practices.EnterpriseLibrary.Common.Configuration.ConfigurationSourceSection,


</configSections>

IfthereisnoenterpriseLibrary.ConfigurationSourcesectionintheconfigurationfile,aninstanceoftheSystemConfigurationSourceclassbecomestheconfigurationsourcefortheapplication.ThismeansthatwhentheapplicationcreatesEnterpriseLibraryobjects,itretrievesconfigurationinformationfromtheapplicationconfigurationfile.

enterpriseLibrary.ConfigurationSourceElement

sourcesElement

instrumentationConfigurationChildElementToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Source Schema for Enterprise Library Core'%0AEntLib50_78c5c78d-846f-4fd8-9671-9a14d10b2e93%0APlease provide details of the error you have located...%0A


UsingEnterpriseLibraryinApplications

EnterpriseLibrarycanbeusedinmosttypesofapplicationsandinthemajorityofscenarioswhereyourequireaneasy-to-useyethighlyflexiblelibrarytohelpyoumanagecrosscuttingconcerns.Forexample,youcanuseEnterpriseLibraryinapplicationbuiltwithWindowsForms,WindowsPresentationFoundation(WPF),WindowsCommunicationFoundation(WCF),ASP.NET,Silverlight®,andconsole-basedapplications.YoucanalsouseEnterpriseLibraryinbothgreenfieldandbrownfieldscenarios.

Whenarchitectingnewapplications,EnterpriseLibrarycanbeusedtoimplementmanyofthecommondesignpatternsyouincorporateinyourdesign.Youcanplanforitsusethroughoutthelayersandcomponentsofyourapplication.YoucanalsouseEnterpriseLibrarysuccessfullyinexistingapplications,whereitcanhelptosimplifythetaskofupdatingoraddingnewfunctionality.Theconfigurationtoolsdonotaffectexistinginformationinyourapplicationconfigurationfiles,andtheassembliesandcodecanbeaddedtoexistingapplicationswithoutfearofconflicts.

EnterpriseLibraryincludessourcecodefortheapplicationblocks,andcompiledandsignedversionsoftheapplicationblockassemblies.Youcanusetheseassembliesdirectly,compiletheapplicationblocksandusethecompiledassemblies,orincludethesourcecodeinyourapplication.However,beforeyoucanusetheassembliesinyourapplication,youmustaddreferencestotherelevantapplicationblockassemblies,andtotheCommonandUnityassemblies.Then,towriteapplicationcode,youalsomustbeawareoftheEnterpriseLibrarynamespaceconventionsandobjectcreationpatterns.

ThissectioncontainsthefollowingtopicsthatwillhelpyoutogetstartedusingEnterpriseLibrary:

ReferencingEnterpriseLibraryAssemblies.Thistopicexplainshowtoaddreferencestotherequiredassembliestoyourapplication,andimporttheseintoyourprojects.DependenciesinEnterpriseLibrary.Thistopicexplainshowsomeoftheblocksdependonothers,andhowalloftheblocksdependoncorefeaturesofEnterpriseLibrary.Itwillhelpyoutounderstandwhichassembliesandfeaturesyourequiredependingontheblocksyouuseand

yourownscenarios.CreatingandReferencingEnterpriseLibraryObjects.ThistopicdescribesthevariouswaysofaccessingEnterpriseLibraryobjects,whattheiradvantagesanddisadvantagesare,anddetailsofhowtheyworkintheunderlyingcode.

Forinformationabouthowtocompiletheapplicationblocks,seeBuildingEnterpriseLibraryfromtheSourceCode.Forinformationaboutthedesignofthedependencyinjectionmechanism,seeTheDependencyInjectionModel.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Enterprise Library in Applications'%0AEntLib50_bf4be8bb-7e39-4a3f-bea0-0e33d90d665b%0APlease provide details of the error you have located...%0A


ReferencingEnterpriseLibraryAssemblies

BeforeyoucanbuildapplicationsthatincorporatetheEnterpriseLibraryapplicationblocks,youmustaddreferencestotheapplicationblockassembliesandtotheCommonandUnityassemblies.ThispreparesyourapplicationtousetheEnterpriseLibrary.TakecaretoselecttheassembliesthatreflectyourdecisiontousetheMicrosoftstrong-namedassemblies,orthenon-strong-namedassemblies,oracustomizedsetofEnterpriseLibraryassemblies.

Toprepareyourapplication1. Addareferencetotheapplicationblockassembly.InVisualStudio,

right-clickyourprojectnodeinSolutionExplorer,andthenclickAddReference.ClicktheBrowsetab,andthenfindthelocationoftheapplicationblockassembly(thescriptCopyAssemblies.batcopiesallapplicationblockassembliestothebinsubdirectory).Selecttheassembly,andthenclickOKtoaddthereference.Forexample,toreferencetheLoggingApplicationBlockassembly,browsetothebinsubdirectory,selecttheassemblyMicrosoft.Practices.EnterpriseLibrary.Logging.dll,andthenclickOK.

2. Usethesameproceduretosetareferencetothefollowingassemblies:Microsoft.Practices.EnterpriseLibrary.Common.dllMicrosoft.Practices.ServiceLocation.dllMicrosoft.Practices.Unity.dllMicrosoft.Practices.Unity.Interception.dll.

Note:YouwillalsoneedtheassemblyMicrosoft.Practices.Unity.Configuration.dllifyouwishtoreferencespecificUnityconfigurationclassesinyourcode.However,inthemajorityofcases,youwillnotrequirethisassembly.

EnterpriseLibraryNamespacesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Referencing Enterprise Library Assemblies'%0AEntLib50_6c04b2bb-aef8-4c8d-a0cc-6ba93ac3d35d%0APlease provide details of the error you have located...%0A


DependenciesinEnterpriseLibrary

ThistopicdescribesthedependenciesbetweentheblocksandonthecorefeaturesofEnterpriseLibrary.Itcontainsthefollowingsectionsthatdescribetheinter-blockdependenciesforcommonscenarios:

DependenciesforAllApplicationBlocksBlockDependencySchematicAdditionalDependenciesfortheCachingApplicationBlockAdditionalDependenciesfortheExceptionHandlingApplicationBlockAdditionalDependenciesforthePolicyInjectionApplicationBlockAdditionalDependenciesfortheSecurityApplicationBlock

DependenciesforAllApplicationBlocks

BlockDependencySchematic

AdditionalDependenciesfortheCachingApplicationBlock

AdditionalDependenciesfortheExceptionHandlingApplicationBlock

AdditionalDependenciesforthePolicyInjectionApplicationBlock

AdditionalDependenciesfortheSecurityApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Dependencies in Enterprise Library'%0AEntLib50_274b7762-57d2-4eeb-900c-6a9a36379b7a%0APlease provide details of the error you have located...%0A


CreatingandReferencingEnterpriseLibraryObjects

ThistopicdiscussesthewaysyoucaninstantiateandaccessEnterpriseLibraryobjects,theadvantagesanddisadvantagesofeachapproach,andmoredetailsabouthowtheyworkintheunderlyingcode.EnterpriseLibraryoffersagreatdealoffunctionality,andmanydifferentwaystoaccessit.Thistopicisintendedtoclarifythechoicesandtohelpyoudeterminewhatwillworkbestforyourapplication.

Typically,youwillcreateinstancesofEnterpriseLibraryobjectsusingoneofthefollowingtwoapproaches:

UsingtheUnityServiceLocator.Thisisthesimplestapproach,andisrecommendedforsimpleapplicationsthathavefewdependencies,andwhereyoudonotwanttotakeadvantageofcontemporaryarchitecturalpatternssuchasdependencyinjection.Itrequiresnoinitializationorsetup.YousimplyconfigureyourapplicationtouseEnterpriseLibraryandthencallthemethodsoftheservicelocatortoobtaininstancesofEnterpriseLibrarytypesondemand.AccessingtheUnityContainerDirectly.Thismoresophisticatedapproachallowsyoutoobtainthefullbenefitsofcontemporaryarchitecturalpatternssuchasdependencyinjectionforyourlayers,components,andcustomtypes.Itrequiresonlyminimalsetup,butmayrequirethatyoumaintainareferencetothecontainerinyourapplication.

Whenyouuseeitheroftheseapproaches,youwilltypicallyrequestandobtainreferencestooneormorenon-staticobjectsandinterfacesthatarepartofeachapplicationblock,whichallowyoutoaccessthefunctionalityoftheblocksandobtaininstancesofEnterpriseLibraryobjectsinyourcodeusingbothdependencyinjectionandtheservicelocatorapproach.Foralistoftheseobjectsandinterfaces,seeNon-StaticInstancesandInstanceFactories.

OtherapproachestocreatingEnterpriseLibraryobjectsthatyoumaychooseinclude:

UsingadifferentservicelocatorifyoudecidetouseacontainerotherthanUnity.Formoreinformationabouthowtheservicelocatorworks,seeInitializingandSettingtheCurrentContainer.FormoreinformationaboutreplacingthedefaultUnitycontainer,seeTheDependency

InjectionModelinthesection"DesignofEnterpriseLibrary".UsingthelegacystaticfacadesandfactoriesthatwerethedefaultapproachinpreviousversionsofEnterpriseLibrary.Formoreinformationaboutthese,seeLegacyStaticFacadesandFactories.

UsingtheUnityServiceLocator

AccessingtheUnityContainerDirectly

Non-StaticInstancesandInstanceFactories

LegacyStaticFacadesandFactories

InitializingandSettingtheCurrentContainer




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating and Referencing Enterprise Library Objects'%0AEntLib50_bfd186b8-9a32-477a-bee7-14742ba1ca42%0APlease provide details of the error you have located...%0A


StoringaReferencetotheContainer

Typically,ifyoudonotuseconstructor,property,ormethodcallinjectiontoresolveandpopulateallofyourapplicationdependenciesduringinitialization,youwillneedtoretainareferencetothecontainerifyouwishtoaccessitdirectlytoresolveobjects.However,therearesomeothersituationsinwhichyoumaywanttobeabletoreferencethecontainerafterinitialization.Thefollowingaresomescenariosinwhichyoumayconsiderstoringareferencetothecontainerforuseinyourcode:

IfyouareusingASP.NETWebFormsorbuildingaWebservice.Youmustbeabletoresolveobjectsforeachpageorservicerequest,anditisquiteexpensiveintermsofresourcesanddoesnotmakesensetocreatethecontainerandloadtheEnterpriseLibraryconfigurationinformationoryourowncustomregistrationseverytime.Inthiscase,youwillusuallystorethepopulatedcontainerintheASP.NETApplicationdictionaryorwithinyourserviceimplementationanduseittoresolveinstancesasrequiredforeachrequest.Ifyouarecreatingaconsoleapplicationoracomponent(ratherthananapplicationwithauserinterfaceoraWebservice).IfyouareusingUnityasyourcontainer,youcancreatethecontainerandloadtheEnterpriseLibrarycontainerextensioninyourstartupcodeandthenuseittoresolvethedependenciesofotherclassesondemandusingtheResolvemethod.Anydependenciesdefinedintheseclasseswillbepopulatedautomatically.Youcanholditinaglobalvariablethroughoutthelifeoftheapplication.Notethatdisposingthecontainerisnotrecommended.Ifyouwanttostoreregistrationsforyourownobjectswithinthecontainer.Youmaychoosetouseaseparatecontainerforthis,thoughyoucanjustaseasilymakeuseofthedefaultcontainerthatholdstheEnterpriseLibraryconfigurationregistrations.Ifyouwanttobeabletoresolveinstancesofobjectsondemandratherthatalwayshavingthemresolvedwhenaclassisinstantiated.Forexample,ifanobjectisonlyrequiredincertaincases(perhapsbasedontherun-timeenvironmentorsomeotherfactor),itmaybeusefultobeabletocallthemethodsthatresolveinstancesfromthecontaineratrun

timeinsteadofusingconstructor,property,ormethodcallinjectiontocreatethemwhentheclassisinitialized.

Thefollowingtablewillhelpyoutounderstandwhenandwhereyoushouldholdareferencetothecontainerinforms-basedandrichclientapplicationsbuiltusingtechnologiessuchasWindowsForms,WindowsPresentationFoundation,andSilverlight.

Task When Where

Createandconfigurecontainer.

Atapplicationstartup.

Mainroutine,startupevents,applicationdefinitionfile,orasappropriateforthetechnology.

Obtainobjectsfromthecontainer.

Atapplicationstartup,andlaterifrequired.

Whereappropriateinthecode.

Storeareferencetothecontainer.


Globalapplicationstate.

Disposethecontainer.

Whentheapplicationshutsdown.

Whereappropriateinthecodeorautomaticallywhentheapplicationends.

Thefollowingtablewillhelpyoutounderstandwhenandwhereyoushouldholdareferencetothecontainerinrequest-basedapplicationsbuiltusingtechnologiessuchasASP.NETWebapplicationsandWebservices.

Task When Where

Createandconfigurecontainer.


HTTPModule(ASP.NETandASMX),InstanceContextextension(WCF).

Obtainobjectsfromthecontainer.

DuringeachHTTPrequest.

Intherequeststarteventorloadevent.Objectsaredisposedwhentherequestends.

Storeareferencetothe


Globalapplicationstateorservicecontext.

container.

Disposethecontainer.

Whentheapplicationshutsdown.

Whereappropriateinthecode.

ResolvinganEntireObjectGraphatApplicationStartup

ResolvingandInjectingObjectsonDemand





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Storing a Reference to the Container'%0AEntLib50_5391b15e-3bc8-41cc-86c3-28a8da60a7dc%0APlease provide details of the error you have located...%0A


WindowsFormsandWPFApplications

Althoughtheyareverydifferenttechnologies,WindowsFormsandWindowsPresentationFoundation(WPF)sharesomefundamentalcharacteristics.Inparticular,theybothusewindowobjectstoimplementtheuserinterfaceandallowyoutospecifywhichcodeshouldrunwhentheapplicationstartsup.Bydefault,thestartupcodesimplyloadsandshowsthemainwindow,butyoucaneasilymodifythistocreateaUnitycontainer,populateitwiththeEnterpriseLibraryconfigurationinformation,andresolvetheobjectsusedbytheapplication.

Forexample,youmaynotwishtocreateallofthewindowsatstartuptominimizestartuptimesormemoryusage.Youcanstoreareferencetothecontaineranduseittoresolvewindowsandothertypesondemand.

Thefollowingsectionscontainmoredetails:WindowsFormsApplicationsWindowsPresentationFoundationApplications

WindowsFormsApplications

WindowsPresentationFoundationApplications




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Windows Forms and WPF Applications'%0AEntLib50_c7948b3a-6bdf-487f-a264-3dbdb51e1a04%0APlease provide details of the error you have located...%0A


ASP.NETWebFormsApplications

InASP.NETWebFormsapplications,therecommendedapproachistostorethecontainerintheglobalstateprovidedbytheApplicationdictionaryobject.Youcanthenaccessthecontainerwhenrequiredor—evenbetter—useanHTTPmoduletoperforminjectiononallofthecontrolsinthepageautomatically.

Ingeneral,youshouldusetheApplicationdictionaryobjecttostorethesingleinstanceofthecontainer.YoumaydecidetocreatechildcontainersofthemaincontainerandstorethemineachuserSessionobject,orevenforeachrequest,toregisteryourcustomtypesandmappingsinthechildcontainers.However,thismayreduceapplicationperformance,andyoushouldgenerallyavoidcreatingadditionalcontainersifpossible.

ThefollowingsectionsdescribethetechniquesandlimitationsforinstantiatingthecontainerinASP.NETapplications.TheyincludeabasicandsimpleapproachtousingtheApplicationobjecttostorethecontainer,followedbytherecommendedapproachthat—whilemorecomplicated—willperforminjectiononthecontrolsinyourpageautomaticallyatruntime:

TheBasicApproach.Thisisthesimplestapproach,whichmaybesuitableinsmallapplicationswherediscoverabilityandtestabilityarelessofaconcern.RecommendedApproachforDependencyInjection.Thistechniquecanperforminjectiononthecontrolsinyourpageautomaticallyatruntime,andprovidebetterdiscoverabilityandtestability.LimitationsandAlternativeApproaches.ThissectiondescribessomeoftheissuesyoushouldbeawareofwhenusingthecontainerinASP.NETapplications.

TheBasicApproach

RecommendedApproachforDependencyInjection

LimitationsandAlternativeApproachesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'ASP.NET Web Forms Applications'%0AEntLib50_21fa11ea-d8db-417b-87ea-1e1ac19b7490%0APlease provide details of the error you have located...%0A


ASP.NETDependencyInjectionHTTPModule

YoucanuseanHTTPmodule,anextensiontotheASP.NETHttpApplicationStateclass,andcodeinGlobal.asaxtoforceASP.NETtoautomaticallyinjectdependentobjectsateverypagerequest,asdiscussedinthetopicASP.NETWebFormsApplications.

ThefollowingcodeshowsasuitableHTTPmodulethatcapturesthePreRequestHandlerExecuteeventtoinsertitselfintotheASP.NETexecutionpipeline.Oneachpagerequest,thehandlerresolvesthecurrentHTTPhandlerthroughthecontainerusingtheBuildUpmethodandthencapturestheOnPageInitCompleteevent.WhentheOnPageInitCompleteexecutes,themodulecodewalksthecompletecontroltree,resolvingeachcontrolthroughthecontainerusingtheBuildUpmethod.

TheBuildUpmethodtakesanexistingobjectinstance,resolvesandpopulatesanydependenciesspecifiedfortheclass,andthenreturnstheinstance.Iftherearenodependencies,itsimplyreturnstheoriginalinstance.C#

usingSystem;

usingSystem.Collections.Generic;

usingSystem.Web;

usingSystem.Web.UI;

usingMicrosoft.Practices.Unity;

namespaceUnity.Web

{

publicclassUnityHttpModule:IHttpModule

{

publicvoidInit(HttpApplicationcontext)

{

context.PreRequestHandlerExecute+=OnPreRequestHandlerExecute;

}

publicvoidDispose(){}

privatevoidOnPreRequestHandlerExecute(objectsender,EventArgse)

{

IHttpHandlercurrentHandler=HttpContext.Current.Handler;

HttpContext.Current.Application.GetContainer().BuildUp(

currentHandler.GetType(),currentHandler);

//UserControlsarereadytobebuiltupafterpageinitializationiscomplete

varcurrentPage=HttpContext.Current.HandlerasPage;

if(currentPage!=null)

{

currentPage.InitComplete+=OnPageInitComplete;

}

}

//Buildupeachcontrolinthepage'scontroltree

privatevoidOnPageInitComplete(objectsender,EventArgse)

{

varcurrentPage=(Page)sender;

IUnityContainercontainer=HttpContext.Current.Application.GetContainer();

foreach(ControlcinGetControlTree(currentPage))

{

container.BuildUp(c.GetType(),c);

}

context.PreRequestHandlerExecute-=OnPreRequestHandlerExecute;

}

//Getthecontrolsinthepage'scontroltreeexcludingthepageitself

privateIEnumerable<Control>GetControlTree(Controlroot)

{

foreach(Controlchildinroot.Controls)

{

yieldreturnchild;

foreach(ControlcinGetControlTree(child))

{

yieldreturnc;

}

}

}

}

}

VisualBasic

ImportsSystem

ImportsSystem.Collections.Generic

ImportsSystem.Web

ImportsSystem.Web.UI

ImportsMicrosoft.Practices.Unity

NamespaceUnity.Web

PublicClassUnityHttpModule

ImplementsIHttpModule

PublicSubInit(ByValcontextAsHttpApplication)_

ImplementsSystem.Web.IHttpModule.Init

AddHandlercontext.PreRequestHandlerExecute,AddressOfOnPreRequestHandlerExecute

EndSub

PublicSubDispose()ImplementsSystem.Web.IHttpModule.Dispose

EndSub

PrivateSubOnPreRequestHandlerExecute(ByValsenderAsObject,ByValeAsEventArgs)

DimcurrentHandlerAsIHttpHandler=HttpContext.Current.Handler

HttpContext.Current.Application.GetContainer().BuildUp(_

currentHandler.[GetType](),currentHandler)

'UserControlsarereadytobebuiltupafterpageinitializationiscomplete

DimcurrentPage=TryCast(HttpContext.Current.Handler,Page)

IfNotcurrentPageIsNothingThen

AddHandlercurrentPage.InitComplete,AddressOfOnPageInitComplete

EndIf

EndSub

'Buildupeachcontrolinthepage'scontroltree

PrivateSubOnPageInitComplete(ByValsenderAsObject,ByValeAsEventArgs)

DimcurrentPage=DirectCast(sender,Page)

DimcontainerAsIUnityContainer=_HttpContext.Current.Application.GetContainer()

ForEachcAsControlInGetControlTree(currentPage)

container.BuildUp(c.[GetType](),c)

Next

RemoveHandlercontext.PreRequestHandlerExecute,AddressOfOnPreRequestHandlerExecute

EndSub

'Getthecontrolsinthepage'scontroltreeexcludingthepageitself

PrivateFunctionGetControlTree(ByValrootAsControl)AsIEnumerable(OfControl)

DimcontrolListAsNewList(OfControl)

ForEachchildAsControlInroot.Controls

IfchildIsNothingThen

ExitFor

Else

controlList.Add(child)

EndIf

ForEachcAsControlInGetControlTree(child)

IfchildIsNothingThen

ExitFor

Else

controlList.Add(child)

EndIf

Next

Next

ReturncontrolList

EndFunction

EndClass

EndNamespace




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'ASP.NET Dependency Injection HTTP Module'%0AEntLib50_a00a4ac8-e45a-4b89-83a1-9f7a78e8e96a%0APlease provide details of the error you have located...%0A


ASP.NETApplicationStateExtension

YoucanuseanHTTPmodule,anextensiontotheASP.NETHttpApplicationStateclass,andcodeinGlobal.asaxtoforceASP.NETtoautomaticallyinjectdependentobjectsateverypagerequest,asdiscussedinthetopicASP.NETWebFormsApplications.

ThefollowingshowsasuitableimplementationofanapplicationstateextensionthatexposesastaticGetContainermethod.ThemethodcreatesanewUnitycontainerintheApplicationstateifonedoesnotalreadyexist,orreturnsareferencetotheexistinginstance.C#

usingSystem.Web;


namespaceUnity.Web

{

publicstaticclassHttpApplicationStateExtensions

{

privateconststringGlobalContainerKey="EntLibContainer";

publicstaticIUnityContainerGetContainer(thisHttpApplicationStateappState)

{

appState.Lock();

try

{

varmyContainer=appState[GlobalContainerKey]asIUnityContainer;

if(myContainer==null)

{

myContainer=newUnityContainer();

appState[GlobalContainerKey]=myContainer;

}

returnmyContainer;

}

finally

{

appState.UnLock();

}

}

}

}

VisualBasic

ImportsSystem.Web


NamespaceUnity.Web

PublicModuleHttpApplicationStateExtensions

PrivateConstGlobalContainerKeyAsString="EntLibContainer"

<System.Runtime.CompilerServices.Extension>_

PublicSharedFunctionGetContainer(appStateAsHttpApplicationState)AsIUnityContainer

appState.Lock()

Try

DimmyContainer=TryCast(appState(GlobalContainerKey),IUnityContainer)

IfmyContainerIsNothingThen

myContainer=NewUnityContainer()

appState(GlobalContainerKey)=myContainer

EndIf

ReturnmyContainer

Finally

appState.UnLock()

EndTry

EndFunction

EndModule

EndNamespace




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'ASP.NET Application State Extension'%0AEntLib50_f8bf058c-60ba-44dd-9729-d1e120f9746f%0APlease provide details of the error you have located...%0A


WCFandASP.NETWebServiceApplications

ToinitializethecontainerandpopulatedependenciesinaWebserviceapplicationrequiresadifferentapproachfromthetypesofapplicationsthatexposeauserinterface(suchasWindowsForms,WPF,andASP.NETWebForms).ThistopicdescribesapossiblesolutionforASP.NETWebservices(ASMX),andpointstoresourcesthatwillhelpyouimplementtheprocessinaWindowsCommunicationFoundation(WCF)application.

ASP.NETWebServiceApplications

WCFApplicationsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'WCF and ASP.NET Web Service Applications'%0AEntLib50_c97facbe-042b-4e3f-a653-4d27100172bd%0APlease provide details of the error you have located...%0A


CreatingApplicationBlockObjects

YoucanresolveinstancesofbothEnterpriseLibraryobjectsandyourowncustomclassesusingthecontainer.TounderstandhowtoresolvetheappropriateEnterpriseLibraryobjects,youmustbeawareofthewaythattheEnterpriseLibraryconfigurationinformationforyourapplicationmapstotheregistrationsinthecontainer.

DefaultandNamedObjectRegistrationsMostoftheEnterpriseLibraryapplicationblocksuseplug-inproviderstoaccomplishtheirtasks,whileprovidingtheflexibilityrequiredforuseinthewidestrangeofscenariosandenvironments.Forexample,youmightaddtwocachemanagerstotheCachingApplicationBlock;onethataccessesadatabasebackingstore,andonethatusesthelocalIsolatedStoragemechanism.IfyouusetheDataAccessApplicationBlock,youmightdefineseveralconnectionstodifferentdatabases,dependingontherequirementsofyourapplication.

Eachproviderisidentifiedbyaname,andthemappingsbetweentheproviderinterfaceorbaseclassandtheconcreteimplementationsoftheprovidersaredifferentiatedbythisname.Anapplicationconfigurationmay,forexample,definetwocachemanagers,DBStoreandLocalStore,whiletheDataAccessApplicationBlockconfigurationmaycontainmappingsnamedCustomerDB,SalesDB,andProductsDB.

Whenyoucreateinstancesoftheseobjectsusinganyoftheapproachesshownintherelatedtopicslistedbelow,youmustprovidethenametoselecttheappropriateobject.However,EnterpriseLibraryalsohastheconceptofadefaultproviderformostoftheblocks.Thisisspecifiedintheconfiguration,anddefinestheproviderthattheblockwilluseifyoudonotspecifyanamedprovider.Whenyouresolveatypewithoutprovidinganame,thecontainerwillreturnaninstanceofthedefaultproviderifitisspecifiedfortheblock.Thisisausefulfeaturethatmakesiteasytoswitchtheapplicationtouseadifferentproviderbyjustchangingthedefaultfortheblockintheconfigurationfile.

Forinformationaboutconfiguringdefaultandnamedproviders,seethetopic"EnteringConfigurationInformation"inthesection"DevelopingApplications"foreachoftheapplicationblocks.

CreatingandResolvingObjectsThefollowingtopicsdescribeinmoredetailthethreemainscenariosforcreatingorinjectinginstancesofobjects:

InjectingResolvedTypesintoOtherClassesResolvingInstancesofTypesUsingUnityCreatingApplicationBlockObjectsDirectly

FordetailsonhowtocreateandreferenceobjectsseeCreatingandReferencingEnterpriseLibraryObjects.ForinformationaboutinitializingtheEnterpriseLibrarycontainerand—ifrequired—storingareferencetoit,seeStoringaReferencetotheContainer.

Note:PreviousversionsofEnterpriseLibraryusedstaticfactorymethodstocreateapplicationblockobjects.ThestaticfacadesandstatictypesareincludedinthisversionofEnterpriseLibrary,andexistingcodethatusesthemwillcontinuetowork.Formoreinformationaboutusingthestaticfacadesandstatictypes,seetheonlineguidanceathttp://msdn.microsoft.com/entlib/.

OnepointtonoteifyouarefamiliarwiththeproviderfactoryapproachforgeneratinginstancesofobjectsusedinversionsofEnterpriseLibrarypriortoversion5.0isthatthestaticfacadesusedintheseearlierversionscannotbeinjected.Newnon-staticfacadesareincludedinthisversionofEnterpriseLibrary.

FormoreinformationaboutUnity,seeUnityDependencyInjectionandInterception.FordetailsofhowUnityintegrateswiththeunderlyingconfigurationmechanisminEnterpriseLibrary,seeTheDependencyInjectionModel.



http://msdn.microsoft.com/entlib/


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Application Block Objects'%0AEntLib50_6453869a-c2bb-4494-9095-ea97d328ee94%0APlease provide details of the error you have located...%0A


InjectingResolvedTypesintoOtherClasses

OneofthemajoradvantagesprovidedbydependencyinjectionmechanismssuchasUnityistheabilitytoautomaticallyinjectresolvedinstancesoftypesintootherclassesatruntime.Thisisthepreferredapproach,asitprovidesseveraladvantagesoverothertechniques(fordetailsoftheseadvantages,seeCreatingandReferencingEnterpriseLibraryObjects.)

Unitysupportsinjectionintotheparametersofconstructorsandmethods,andtosetthevalueofproperties.ThismeansthatyoucaneasilyinjectinstancesoftheEnterpriseLibraryobjectsandyourowncomponentsandservicesintocustombusinessobjectsandothercomponents.Thefollowingsectionsofthistopicprovidemoreinformation:

UsingConstructorInjectionUsingProperty(Setter)InjectionUsingMethodCallInjection

Note:OthertopicsinthissectionshowhowyoucanresolveinstancesofEnterpriseLibraryobjectsondemand,andhowyoucancreateinstancesofEnterpriseLibraryobjectsdirectly.Formoreinformation,seeResolvingInstancesofTypesUsingUnityandCreatingApplicationBlockObjectsDirectly.

Usingconstructor,method,andpropertyinjectionallowsyoutoinjectinstancesofresolvedtypesnotonlyintothetargettype(thetypeyouareactuallyresolving),butitalsopopulatesdependenciesinallresolvedtypes.Thefollowingschematicshowsanoverviewoftheprocess.

FormoredetailedinformationaboutthedependencyinjectionfeaturesofUnity,seeUnityDependencyInjectionandInterception.

UsingConstructorInjection

UsingPropertyInjection

UsingMethodCallInjectionToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Injecting Resolved Types into Other Classes'%0AEntLib50_58a17e62-fad7-4099-9f77-7ef780f1277d%0APlease provide details of the error you have located...%0A


ResolvingInstancesofTypesUsingUnity

ThistopicdiscussesthemethodsthatUnityprovidesforresolvingtypesandcreatinginstancesoftypes.ItalsodescribeshowyoucanresolveinstancesofEnterpriseLibraryobjectsandyourowncustomtypes.Thetopicsarethefollowing:

TheUnityResolveMethodResolvingInstancesofEnterpriseLibraryTypesResolvingInstancesofYourOwnCustomTypes

Note:Othertopicsinthissectionshowhowyoucaninjectresolvedinstancesintoyourowncustomclasses,andhowyoucancreateinstancesofEnterpriseLibraryobjectsdirectly.Formoreinformation,seeInjectingResolvedTypesintoOtherClassesandCreatingApplicationBlockObjectsDirectly.

TheUnityResolveMethod

ResolvingInstancesofEnterpriseLibraryTypes


ResolvingInstancesofYourOwnCustomTypesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Resolving Instances of Types Using Unity'%0AEntLib50_7110a918-e653-4f4d-9a1a-43585943613e%0APlease provide details of the error you have located...%0A


CreatingApplicationBlockObjectsDirectly

Therearetimeswhentheconfigurationinformationforyourapplicationscenariodoesnotresideinaconfigurationsource.Forexample,yoursystemmaydynamicallycreateconfigurationinformationfromdataenteredbyauser.Forthesesituations,youcandirectlyconstructapplicationblockobjects,passingtherequiredconfigurationinformationtotheconstructor.

Note:Othertopicsinthissectionshowhowyoucaninjectresolvedinstancesintoyourowncustomclasses,andhowyoucanresolveinstancesofEnterpriseLibraryobjectsondemand.Formoreinformation,seeInjectingResolvedTypesintoOtherClassesandResolvingInstancesofTypesUsingUnity.

Whenyouconstructanapplicationblockobject,youmustconstructaspecificproviderimplementationtypeusingtheappropriateconstructorparametersandpasstherequiredargumentstotheconstructor.ThefollowingcodeshowshowtoconstructtheDataAccessApplicationBlockSqlDatabaseobject.C#

StringconnString=@"server=(local)\SQLEXPRESS;database=EntLibTest;"+"IntegratedSecurity=true";

SqlDatabasedb=newSqlDatabase(connString);

VisualBasic

DimconnStringAs[String]="server=(local)\SQLEXPRESS;database=EntLibTest;"+_

"IntegratedSecurity=true"

DimdbAsNewSqlDatabase(connString)

ConfigurationInformationforNewObjectsSomeobjectconstructorshaveanoverloadthatacceptsaninstanceofaconfigurationsourcethatimplementstheIConfigurationSourceinterface.Thisallowsyoutosupplyconfigurationinformationdirectlytothenewobject.

DependencyInjectionforExistingObjectsWhenyoucreateinstancesofobjectswithoutusingtheUnitydependencyinjectionmechanism,dependentobjectsarenotautomaticallyinjectedintoyournewobject.However,youcanforceUnitytoresolveandpopulatedependenciesbyusingtheBuildUpmethodofthecontainer.KeepinmindthatconstructorinjectiondoesnottakeplacewhenyouusetheBuildUpmethodbecausetheobjectalreadyexistsandsotheconstructordoesnotexecute.

ThefollowingexampleshowshowyoucanusetheBuildUpmethodtoapplydependencyinjectiontoanexistingobjectinstancenamedmyDataServicethatimplementstheinterfaceIMyService.FormoreinformationabouttheBuildUpmethod,seeUsingBuildUptoWireUpObjectsNotCreatedbytheContainerintheUnitydocumentation.C#

IMyServicemyDataService=newDataService();

IMyServicebuiltupDataService=container.BuildUp<IMyService>(myDataService);

VisualBasic

DimmyDataServiceAsIMyService=NewDataService()

DimbuiltupDataServiceAsIMyService=container.BuildUp(OfIMyService)(myDataService)

Note:EnterpriseLibraryincludescodetoenableinstrumentation.Ifyoudirectlyconstructapplicationblockobjects,instrumentationwillnotbeenabledforthoseobjects.However,inmostcases,youcanbindtheappropriateinstrumentationproviderstotheapplicationproviders.Formoreinformationaboutinstrumentationlistenersandinstrumentationproviders,seeEnablingInstrumentation.



[email protected].


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Application Block Objects Directly'%0AEntLib50_dc9bdf09-7ac5-4ab9-846d-8f5c6d29fe3e%0APlease provide details of the error you have located...%0A


DeployingEnterpriseLibrary

TheEnterpriseLibraryApplicationBlocksarecomprisedofmultipleassemblies.EachassemblythatbelongstotheEnterpriseLibrary(excludingUnity,whichisagenericutility)hasafilenamethatbeginswithMicrosoft.Practices.EnterpriseLibrary.Additionally,theapplicationblocksmaydependontheEnterpriseLibrarycommonassemblies.Anapplicationthatusesoneormoreoftheapplicationblocksmayhavedependenciesonotherapplicationblocks.Forexample,someapplicationsthatusetheCachingApplicationBlockalsorequiretheDataAccessApplicationBlockassemblies.ForinformationaboutthedependenciesbetweentheapplicationblocksandtheEnterpriseLibraryCore,seeDependenciesinEnterpriseLibrary.

AnapplicationthatusestheEnterpriseLibraryapplicationblockscanbedeployedinoneoftwoconfigurations:

Asprivateassembliesintheapplicationfolderhierarchy.Assharedassembliesinanyfilesystemlocationorintheglobalassemblycache.

Specificdeploymentrecommendationsareincludedinthedocumentationforeachapplicationblock.Formoreinformation,seethedeploymenttopicfortheindividualapplicationblock.ForgeneralinformationaboutpreparingandversioningEnterpriseLibraryandusingtheglobalassemblycache,seePreparationandVersioning.

Note:IfyoudecidetolocatetheEnterpriseLibraryassembliesintheglobalassemblycache,therearesomeextrastepsyoumusttakeifyouusetheDataAccessApplicationBlockandtheValidationApplicationBlock.Thesearedescribedinthesection"UsingtheGlobalAssemblyCache"inthetopicPreparationandVersioning,andathttp://entlib.codeplex.com/WorkItem/View.aspx?WorkItemId=26903.

EnterpriseLibraryincludespre-compiledstrong-namedassembliesforallthesourcecode.TheassembliesaresignedwithaMicrosoftstrong-namingkeythat

http://entlib.codeplex.com/WorkItem/View.aspx?WorkItemId=26903

isnotincludedwiththesourcecode.Thismeansthatyoucannotbuildacompiledversionfromthesourcecodethatusesthesamepublickey.However,youcanuseyourownkeypairtocreatestrong-namedassemblies.IfyoubelievethatyoumaycustomizetheEnterpriseLibrarysourcecode,youshouldusethebinariesthatyoucompilefromthesourcecodeandsignwithyourownkeyinsteadofusingthepre-compiledbinariessignedwiththeMicrosoftkey.

Formoreinformation,seeBuildingEnterpriseLibraryfromtheSourceCodeandStrongNamingtheEnterpriseLibraryAssemblies.

Ifyouupdateanyoftheapplicationblocks,orifyouwanttoinstallanupdatedversionofanassembly,youcaninstallthenewversionandhaveallapplicationsusetheupdatedassembly.Alternatively,youcaninstallthenewversionintheglobalassemblycacheandconfiguresomeapplicationstousetheupdatedversion,whileotherscontinuetousetheearlierversion.Formoredetails,seeUpdatingApplicationBlockAssemblies.

Ifyouintendtorunyourapplicationinpartialtrustenvironments,inparticularusingacustomizedASP.NETMediumTrustmode,seePartialTrustEnvironments.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deploying Enterprise Library'%0AEntLib50_10966b86-db1f-40de-95ff-b84e2cdfff20%0APlease provide details of the error you have located...%0A


PreparationandVersioning

WhenyoucompiletheinstalledversionoftheEnterpriseLibrarysourcecode,theassembliesproducedwillnotbestrongnamed.Asaresult,theycannotbeinstalledintheglobalassemblycache,norwilltheyhavetheotherbenefitsassociatedwithstrong-namedassemblies.

UsingXCopy

UsingtheGlobalAssemblyCache

http://entlib.codeplex.com/WorkItem/View.aspx?WorkItemId=26903


VersioningToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://msdn2.microsoft.com/en-us/library/wd40t7ad(vs.71).aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Preparation and Versioning'%0AEntLib50_7fc82b31-039c-4b54-9442-e9e2d866a10d%0APlease provide details of the error you have located...%0A


BuildingEnterpriseLibraryfromtheSourceCode

AlthoughtheEnterpriseLibraryincludesbinariesforallthesourcecode,youmaywanttocustomizethesourcecode.ThismeansyouwillneedtobuildtheEnterpriseLibraryyourself.Thefollowingsectionsdescribehowtodothis.Afteryouhavethebinaries,youmaywanttostrongnamethem.Formoreinformationaboutthistopic,seeStrongNamingtheEnterpriseLibraryAssemblies.

Thistopiccontainsthefollowingsubsections:InstallingtheSourceCodeEnterpriseLibraryVisualStudioSolutionFilesBuildingtheEnterpriseLibraryApplicationBlocksandToolsBuildingtheEnterpriseLibraryUsingMicrosoft.NetFramework4.0AdditionalNotesforBuildingandUsingtheSourceCode

InstallingtheSourceCode

EnterpriseLibraryVisualStudioSolutionFiles

BuildingtheEnterpriseLibraryApplicationBlocksandTools

AdditionalNotesforBuildingandUsingtheSourceCodeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Building Enterprise Library from the Source Code'%0AEntLib50_e13a03ac-387f-4300-bff0-f97c33628f47%0APlease provide details of the error you have located...%0A


StrongNamingtheEnterpriseLibraryAssemblies

IfyoubuildEnterpriseLibraryfromthesourcecode,youmaydecidetoapplystrongnamingtotheassemblies.Astrongnameconsistsoftheassembly'sidentity—thesimpletextname,versionnumber,andcultureinformation(ifprovided)—plusapublickeyandadigitalsignature.Thestrongnameisgeneratedfromanassemblyfile(thefilethatcontainstheassemblymanifest,whichinturncontainsthenamesandhashesofallthefilesthatmakeuptheassembly),usingthecorrespondingprivatekey.Signinganassemblywithastrongnameensuresthatitsnameisgloballyunique.Assemblieswiththesamestrongnameareexpectedtobeidentical.

Forexample,ifyouintendtosharetheEnterpriseLibraryassembliesamongseveralapplications,youcaninstallthemintotheglobalassemblycache.EachassemblyintheGACmusthaveagloballyuniquename.Youcanuseastrongnametoensurethis.Evenifyouusetheassemblieswithinonlyasingleapplication,youcanstrongnamethemtoensurethatyourapplicationusestheircorrectversions.

Strongnamessatisfythefollowingrequirements:Strongnamesguaranteenameuniquenessbyrelyingonuniquekeypairs.Noonecangeneratethesameassemblynamethatyoucanbecauseanassemblygeneratedwithoneprivatekeyhasadifferentnamethananassemblygeneratedwithanotherprivatekey.Strongnamesprotecttheversionlineageofanassembly.Astrongnamecanensurethatnoonecanproduceasubsequentversionofyourassembly.Userscanbesurethataversionoftheassemblytheyareloadingcomesfromthesamepublisherthatcreatedtheversionoriginallyprovidedwiththeapplication.Strongnamesprovideastrongintegritycheck.Passingthe.NETFrameworksecuritychecksguaranteesthatthecontentsoftheassemblyhavenotbeenchangedsinceitwasbuilt.However,notethatstrongnamesalonedonotimplyaleveloftrustsuchasthatprovidedby,forexample,adigitalsignatureandsupportingcertificate.

Forinformationaboutdeployingassembliesintotheglobalassemblycache,seeWorkingwithAssembliesandtheGlobalAssemblyCache.

http://msdn2.microsoft.com/en-us/library/6axd4fx6.aspx

UsingVisualStudiotoStrongNameEnterpriseLibraryAssembliesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Strong Naming the Enterprise Library Assemblies'%0AEntLib50_8bc6cce9-1935-4b82-a1ad-9fbd4a91fc1e%0APlease provide details of the error you have located...%0A


UpdatingApplicationBlockAssemblies

IfanupgradedversionofanEnterpriseLibraryApplicationBlockbecomesavailable,youcaninstallthenewversionandhaveallapplicationsusetheupdatedassembly.However,ifthenewversionintroducescompatibilityproblemsforcertainapplications,youcaninstallthenewversionintheglobalassemblycacheandconfiguresomeapplicationstousetheupdatedversion,whileotherscontinuetousetheearlierversion.

UpdatingPrivateAssemblies

UpdatingSharedAssembliesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Updating Application Block Assemblies'%0AEntLib50_2fe3ef51-528f-4fd6-8492-1a1b07d9fae9%0APlease provide details of the error you have located...%0A


PartialTrustEnvironments

ApplicationsthatuseversionsoftheEnterpriseLibrarypriortoversion3.0requireenoughpermissionssothattheonlysecurityleveltheycanuseisfulltrust.WithlaterversionsofEnterpriseLibrary,includingthisversion,youcanrunapplicationsunderpartialtrust.AcommonexampleisanASP.NETapplicationthatrunsinahostedenvironment.Typically,thesetypesofapplicationsrequireonlyenoughpermissionstorunundermediumtrust.DependingontheEnterpriseLibraryfeaturesthatyourapplicationuses,youmayneedtograntadditionalpermissionsbeyondthosegrantedbyadefaultpartial-trustpolicy.

Thistopiccontainsthefollowingsections:OverviewofPartialTrustEnterpriseLibraryandPartialTrustEnterpriseLibraryCodeAccessSecurityandtheSecurityTransparentAttribute

OverviewofPartialTrust

http://msdn.microsoft.com/en-us/library/930b76w0.aspx


http://msdn2.microsoft.com/en-us/library/7c9c2y1w.aspx

EnterpriseLibraryandPartialTrust

EnterpriseLibraryCodeAccessSecurityandtheSecurityTransparentAttributeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Partial Trust Environments'%0AEntLib50_fe303e51-5b35-4c36-9bf6-406f0751e14b%0APlease provide details of the error you have located...%0A


CustomizingtheMediumTrustPolicy

Thetablesinthefollowingsectionsshowtheadditionalpermissions—beyondthosegrantedbydefaultinthemediumtrustpolicy—thatmayberequiredbyyourapplication.Youneedtogranttheseadditionalpermissionsonlyifyouwanttousethesespecificfeatures.Unlessotherwisenoted,makethesemodificationsinthecustompolicyfile.

Forextendedexamplesofhowtomodifyacustompolicyfile,seeHowTo:UseMediumTrustinASP.NET2.0onMSDN.Ifyouareusingapartial-trustpolicyotherthanmediumtrust,otherrestrictionsandpermissionsmayapply.Foratablethatliststhedifferentpermissionsandthetrustpoliciesthatallowthem,seeASP.NETCodeAccessSecurityonMSDN.

Theseadditionalpermissionsarethefollowing:GeneralPermissionsCachingApplicationBlockPermissionsCryptographyApplicationBlockPermissionsDataAccessApplicationBlockPermissionsExceptionHandlingApplicationBlockPermissionsLoggingApplicationBlockPermissionsSecurityApplicationBlockPermissionsPolicyInjectionApplicationBlockPermissionsValidationApplicationBlockPermissions

Thenextsectionsdescribethesepermissions.

http://msdn2.microsoft.com/en-us/library/ms998341.aspx

http://msdn2.microsoft.com/en-us/library/87x8e4d1.aspx

GeneralPermissions

CachingApplicationBlock

CryptographyApplicationBlock

DataAccessApplicationBlock

ExceptionHandlingApplicationBlock

LoggingApplicationBlock

SecurityApplicationBlock

PolicyInjectionApplicationBlock

ValidationApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Customizing the Medium Trust Policy'%0AEntLib50_3ec66771-43d1-4db1-b604-609018478f1b%0APlease provide details of the error you have located...%0A


LimitationsWhenUsingPartialTrust

TheremaybesomelimitationsregardinghowyouusepartialtrustwithanEnterpriseLibraryapplicationblock.Theselimitationsincludethefollowing:

EnterpriseLibrarythrowsaSecurityExceptionifitcannotobtainthemandatorypermissions.SomecallstoLoggingApplicationBlocktracelistenerclassesfail.ASP.NETapplicationdirectoriesrequirespecificpermissions.TheAzManproviderisnotavailablewithpartialtrust.

EnterpriseLibraryThrowsSecurityException

LimitationsonLoggingApplicationBlockTraceListeners

ASP.NETApplicationDirectoriesRequirePermissions

AzManProviderNotAvailableToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Limitations When Using Partial Trust'%0AEntLib50_aef042e4-bd38-4280-876e-d6d39174564e%0APlease provide details of the error you have located...%0A


AdministeringEnterpriseLibrary

ThistopicdescribessomeofthemainscenariosforsystemadministratorsandoperatorswhomanageapplicationsthatuseEnterpriseLibrary.Ingeneral,theprocessesandtechniquesarenodifferentfromthoseinvolvedinmanagingany.NETapplication.However,EnterpriseLibrarydoesprovideseveralusefulfeaturesdesignedtomakeadministrationandmanagementeasier.Thissectioncoversthefollowingtopics:

RunningMultipleVersionsofEnterpriseLibraryRunTimeConfigurationChangestotheRunTimeEnvironmentInstrumentationwithintheApplicationBlocksIntegrationwithEnterpriseManagementToolsDebuggingUsingtheSourceCode

RunningMultipleVersionsofEnterpriseLibrary

RunTimeConfiguration

ChangestotheRunTimeEnvironment

InstrumentationwithintheApplicationBlocks

IntegrationwithEnterpriseManagementTools

DebuggingUsingtheSourceCodeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Administering Enterprise Library'%0AEntLib50_92689f11-4ae5-446c-ba53-1d8deecd38b9%0APlease provide details of the error you have located...%0A


ExtendingandModifyingEnterpriseLibrary

EnterpriseLibrarycanserveasthebasisforacustomlibrary.Youcantakeadvantageoftheextensibilitypointsincorporatedineachapplicationblockandextendtheapplicationblockbysupplyingnewproviders.Youcanalsomodifythesourcecodefortheexistingapplicationblockstoincorporatenewfunctionality.UsetheguidelinesinthistopicwhenyouextendtheEnterpriseLibrary.

TherearethreewaystoextendtheEnterpriseLibrary.Youcan:Writecustomproviders.Fordetailedinformationaboutcreatingprovidersandextensionsforeachapplicationblock,seethe"ExtendingandModifying"topicinthesectionsofthisdocumentationforeachoftheblocks.Forgeneralinformationaboutcreatingcustomproviders,andintegratingwiththeconfigurationtools,seeCreatingCustomProvidersforEnterpriseLibrary.Modifythesourcecodeofanapplicationblock.Formoreinformationaboutthedesignofeachblock,seethetopic"DesignoftheApplicationBlock"inthesectionsofthisguidancedevotedtoeachoftheapplicationblocks.Writeanewapplicationblock.Youcanusetheexistingblocksasguidancetocreateacompletelynewblock.YouwillalsofindadditionalinformationandresourcesoncreatingandextendingtheblocksontheEnterpriseLibrarycommunitycontributionssiteathttp://www.codeplex.com/entlibcontrib/.

ThefollowingsectionsexplainsomeofthefactorstokeepinmindwhenextendingormodifyingEnterpriseLibrary.

http://www.codeplex.com/entlibcontrib/

GuidelinesforExtendingEnterpriseLibrary

http://msdn.microsoft.com/en-us/library/czefa0ke(VS.71).aspx



GuidelinesforModifyingtheApplicationBlocksToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying Enterprise Library'%0AEntLib50_ebcb0d9f-ee0c-4599-9f21-1df89b878381%0APlease provide details of the error you have located...%0A


CreatingCustomProvidersforEnterpriseLibrary

EnterpriseLibraryincorporatesaneasy-to-useextensiblemechanismforyoutoaddyourowncustomprovidersifyourequirespecializedbehavior.YoucanplugincustomprovidersthatyoucreatewithoutneedingtorecompileEnterpriseLibrary.

Inaddition,theconfigurationmechanismmakesiteasytoaddafulldesign-timeexperiencetoyourcustomproviderssothattheycanbeconfiguredwithintheconfigurationtoolsinexactlythesamewayasthebuilt-inproviders.Theconfigurationtoolsaremetadatadriven,andreadinformationaboutavailableprovidersandextensionsfromassemblieslocatedintheirrun-timefolderonstartup.Thismeansthatyoudonotneedtorecompiletheconfigurationtooltoaddadesign-timeexperienceforyourcustomproviders.

ThefollowingtopicsdescribethegeneralprocessforcreatingacustomproviderforEnterpriseLibrary,andincludeanexampleofasimpleprovider:

EnterpriseLibraryExtensionPoints.ThistopicliststheextensionpointsforEnterpriseLibrary,andtheclassesyoucanusewhencreatingacustomproviderandspecifyingconfigurationinformationforit.EnterpriseLibraryConfigurationIntegration.ThistopicdescribesthetwowaysthatyoucanintegratecustomprovidersintotheEnterpriseLibraryconfigurationsystem.CreatingaCustomProvider.ThistopicprovidestheinformationrequiredforcreatingaproviderthatyouaddtotheapplicationconfigurationusingtheAddCustom[providertype]menucommandsintheconfigurationtools,andexplainshowyoucancreateafullyintegrateddesign-timeexperienceforacustomprovider.

YoucandownloadaVisualStudioprojectcontainingtheexampleproviderdescribedinthissection.Theprojectincludesacustomexceptionhandlerinbothbasicandfullconfigurationintegrationmodes,andasimpleconsoleapplicationthatusesbothversionsofthehandler.Todownloadthesample,gotohttp://www.codeplex.com/entlib/.

Note:


ThissectiondoesnotcoverextendingtheUnitydependencyinjectionandinterceptionmechanism.ForinformationabouthowyoucanextendUnity,seethedocumentationavailableontheUnityWebsiteathttp://www.codeplex.com/unity/.



http://www.codeplex.com/unity/


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Custom Providers for Enterprise Library'%0AEntLib50_3d7d908a-3382-4d75-9909-c968dfade305%0APlease provide details of the error you have located...%0A


EnterpriseLibraryExtensionPoints

ThefollowingtableslisttheextensionpointsthatEnterpriseLibraryprovidesforeachoftheapplicationblocks.Foreachtypeofproviderorextension,thetablesshow:

Theinterfaceyoucanimplementand/orthebaseclassyoucaninherit.Thetypeoftheconfigurationelementtoapplytoyourcustomclasstoenablebasicintegrationwiththeconfigurationsystem.Thebaseclassthatyoumustinheritinyourcustomconfigurationelementifyouwanttoimplementfulldesign-timeconfigurationintegration.Yourcustomproviderorextensionwillthenuseyourcustomconfigurationelementclassasitsconfigurationelementtype,insteadofthedefaultshownintheConfigurationElement(basicintegration)column.

ProvidersandextensionsthatcannotbeintegratedwiththeconfigurationtoolshavenoentryintheConfigurationElement(basicintegration)column.

CachingApplicationBlock

CustomProviderorExtension

InterfaceorBaseClass

ConfigurationElement(basicintegration)

ConfigurationElementBaseClass(designtimeintegration)

BackingStore

IBackingStoreBaseBackingStore

CustomCacheStorageData CacheStorageData

CacheManager

ICacheManager CustomCacheManagerData CacheManagerDataBase

ExpirationPolicy

ICacheItemExpiration n/a n/a

StorageEncryptionProvider

IStorageEncryptionProvider n/a StorageEncryptionProviderData

CryptographyApplicationBlock




HashAlgorithmProvider

IHashProvider CustomHashProviderData

SymmetricEncryptionAlgorithmProvider

ISymmetricCryptoProvider CustomSymmetricCryptoProviderData

DataAccessApplicationBlock





DatabaseProvider

Database n/a n/a

ExceptionHandlingApplicationBlock





ExceptionHandler

IExceptionHandler CustomHandlerData ExceptionHandlerData

ExceptionFormatter

ExceptionFormatter n/a n/a

LoggingApplicationBlock





LogEntryFormatter

ILogFormatter CustomFormatterData FormatterData

TraceListener

CustomTraceListener CustomTraceListenerData TraceListenerData

LogFilter ILogFilterLogFilter

CustomLogFilterData LogFilterData

IfyouimplementacustomLogFilterbyimplementingtheILogFilterinterfaceorbyextendingtheLogFilterbaseclass,youmustbeawareofanissuethatcanpreventapplicationcodefromresolvingtheconfigurednameoftheprovider.However,thisisonlyanissuewhenyouwishtoquerythecollectionoffilterswhencheckingifalogentrywillbespecificallyblockedbythisfilter.TheILogFilterinterfacedefinesaNamepropertythatshouldreturnthenameoftheinstanceofthecustomlogfilterfromtheconfiguration.However,therecurrentlyisnowaytoretrievethatnamefromwithinyourcustomlogfilter.Instead,youcanpassakey/valuepairintheNameValueCollectionreceivedbytheconstructor,andusethistosettheNamepropertyofthefilter.Whenconfiguringyourcustomlogfilter,youwillhavetoduplicatethename:oncefortheactualnameofthatinstanceofthecustomlogfilter,andagaininthenamedpropertycollectionthatispassedtotheconstructor.

PolicyInjectionApplicationBlockPolicyinjectionisafeaturedrivenbytheUnityinterceptionmechanism.Youcancreatecustombehaviors,callhandlers,callhandlerattributes,andmatchingrulesforusewiththeUnityinterceptionmechanism.Formoreinformation,seehttp://www.codeplex.com/unity/.


SecurityApplicationBlock





AuthorizationProvider

AuthorizationProvider CustomAuthorizationProviderData AuthorizationProviderData

SecurityCacheProvider

ISecurityCacheProvider CustomSecurityCacheProviderData SecurityCacheProviderData

ValidationApplicationBlock





Validator Validator<T>Validator

CustomValidatorData ValidatorData

ValidatorAttribute

ValueValidatorAttribute n/a n/a

FormoreinformationaboutcreatingcustomprovidersandextensionsforEnterpriseLibrary,seeEnterpriseLibraryConfigurationIntegrationandCreatingaCustomProvider.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Enterprise Library Extension Points'%0AEntLib50_cb80a94d-5ff9-4384-8806-b84382a3e975%0APlease provide details of the error you have located...%0A


EnterpriseLibraryConfigurationIntegration

EnterpriseLibraryallowsyoutoeasilyintegratecustomprovidersandextensionsintothelibraryinsuchawaythatyoucanconfigurethemusingtheEnterpriseLibraryconfigurationtools.Therearetwotypes,orlevels,ofconfigurationintegration.

BasicConfigurationIntegration

FullConfigurationIntegrationToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Enterprise Library Configuration Integration'%0AEntLib50_090c3f47-afb3-478d-b20a-9caf5bde3e97%0APlease provide details of the error you have located...%0A


CreatingaCustomProvider

Thefollowingstepsdescribetheprocessforcreatingacustomprovider:PreparingYourProjectImplementingtheInterfaceorExtendingtheBaseClassSpecifyingtheConfigurationElementTypeAddingFullDesign-timeIntegrationSummaryofSteps

PreparingYourProject

ImplementingtheInterfaceorExtendingtheBaseClass

SpecifyingtheConfigurationElementType

AddingFullDesign-timeIntegration

SummaryofStepsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating a Custom Provider'%0AEntLib50_aa02ad32-54e2-4fa3-91d8-b2c4bfbe14c7%0APlease provide details of the error you have located...%0A


DesignofEnterpriseLibrary

EnterpriseLibraryincorporatesasetofbestpracticesinitsoveralldesign.Amongthesearethefollowing:

Itusescommonapplicationblockfunctionality(theEnterpriseLibraryCore).Itusesuniformconventionsfornamingandversioning.Itincorporatesinstrumentationintoallapplicationblocks.Itusesunittestswrittenduringthedesignphase.

ThesectiondescribesthedesignofEnterpriseLibraryandincludesthefollowingtopics:

DesignPatterns.ThistopicdescribestheuseofdesignpatternswithinEnterpriseLibrary.TheEnterpriseLibraryCore.ThistopicdescribestheEnterpriseLibraryCore,includingtheconfigurationsystem.Providers.Thistopicdescribestheuseofproviderstoimplementextensibility.DesignTimeConfiguration.Thistopicdescribesthedesign-timeconfigurationfeaturesofEnterpriseLibrary.TheDependencyInjectionModel.ThistopicdescribesthedependencyinjectionmechanismusedbyEnterpriseLibrarytoinstantiateobjectsandmanagetheirlifetimes.Instrumentation.ThistopicdescribestheimplementationofinstrumentationwithinEnterpriseLibrary.GroupPolicySupport.ThistopicdescribesGroupPolicysupportusingtheManageableConfigurationSource.UnitTests.ThistopicdescribestheuseofunittestswithinEnterpriseLibrary.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of Enterprise Library'%0AEntLib50_93b0aa98-98b7-4f7a-b7b3-f3ac52852d50%0APlease provide details of the error you have located...%0A


DesignPatterns

Insoftwarearchitectureanddevelopment,apatternisadescriptionofarecurringproblemthatoccursinaspecificcontextand,basedonasetofguidingforces,suggestsasolution.Thesolutionisusuallyasimplemechanismbecauseitisacollaborationbetweentwoormoreclasses,objects,services,processes,threads,components,ornodesthatworktogethertosolvetheunderlyingarchitectureordevelopmentchallenge.

Patternsareusefultodevelopersandarchitectsbecausetheydothefollowing:Theydocumentsimplemechanismsthatwork.Theyprovideacommonvocabularyandtaxonomyfordevelopersandarchitects.Theyallowsolutionstobedescribedconciselyascombinationsofpatterns.Theyenablereuseofarchitecture,design,andimplementationdecisions.

TheEnterpriseLibraryapplicationblocksusethefollowingpatterns(amongothers):

Plug-inpattern.Thispatternextendsthebehaviorofaclassbyallowingextensionstoplugintoanabstractclassthat,inturn,plugsintoacoreclass.Thiscreatesanewsubclassthatincludesonlythecapabilitiesrequiredinthespecificcontext.DependencyInjectionpattern.Withthispattern,youcaninjectobjectsintoaclass,insteadofrelyingontheclasstocreatetheobject.

Formoreinformationaboutpatterns,seetheMicrosoftpatterns&practicesWebsite.

http://msdn.microsoft.com/practices/

Plug-inPattern

DependencyInjectionPatternToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://www.martinfowler.com/articles/injection.html


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design Patterns'%0AEntLib50_68e82ab7-4cf9-4303-94fb-3afcc733f88f%0APlease provide details of the error you have located...%0A


TheEnterpriseLibraryCore

ManytasksthattheEnterpriseLibraryapplicationblocksperformarecommonacrossmorethanoneapplicationblockandarealsousefulinapplicationcodeoutsideofEnterpriseLibrary.Examplesareroutinesthatserializedataoraccessconfigurationinformation.Topromoteusability,theseroutinesresideinacommonassemblynamedtheEnterpriseLibraryCore.

Inaddition,alltheapplicationblocksaredesignedtohavealimitednumberofdependenciessothattheycanbeusedindividuallyaswellaswithotherapplicationblocks.AllapplicationblocksexceptUnitydependontheEnterpriseLibraryCore,whichisalogicalgroupingmadeupofthefollowingsubsystems:

TheCommonassemblyInstrumentationfortheapplicationblocksConfigurationhelperclassesanddesign-timeconfigurationcomponents

ForinformationaboutthedependenciesbetweenapplicationblocksandtheEnterpriseLibraryCore,seeDependenciesinEnterpriseLibrary.

TheCommonAssembly

Instrumentation

ConfigurationHelperClassesandDesign-timeComponentsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Enterprise Library Core'%0AEntLib50_5dca2781-1fa7-4f76-a5cf-11fc3faf6cf1%0APlease provide details of the error you have located...%0A


Providers

AproviderintheMicrosoft.NETFrameworkisanintermediarypieceofcode;withit,yourapplicationcanconnecttoaserviceordatasourceandthenretrieveormodifyanobjectordatafromthatserviceorsource.TheEnterpriseLibraryincludesmanyproviders.Inaddition,youcancreateyourownprovidertosupplyinformationthatyouneedforyourspecificapplication.

Aprovidertypedefinesaninterfacethatisassociatedwithacapabilityanapplicationblockmusthavetoperformcorrectly.Aproviderisaspecificimplementationofaprovidertype.Eachapplicationblockincludesoneormoreprovidersforeachprovidertype.Youcanalsowritecustomprovidersforapplicationblocks.Separatingtheapplicationblock'sfunctionalityfromspecificimplementationsofitscapabilitiesachievesthefollowinggoals:

Variability.Thisallowsyoutochoosefrommultipleimplementationsofthesamecapability,accordingtotherequirementsofaspecificapplication.Extensibility.Thisallowsyoutousetheapplicationblockinenvironmentswherethecapabilityinquestionhasamandatoryimplementation.Forexample,anapplicationcanrequireaspecificencryptionalgorithmwhendeployedtoaparticularenvironment.Encapsulation.Thisallowsyoutoreacttochangesintheenvironmentinwhichtheapplicationblockisused.Withproviders,functionalitythatisnotapartoftheapplicationblock'scorefunctionalitycanbereplacedorupgradedwithoutaffectingotherareasoftheapplicationblock.Portabilityacrossenvironments.Thisallowsyoutodeploytheapplicationblockinanewenvironmentwithprovidersspecifictothatenvironment.Youcanalsocreateprovidersthatruninoneenvironmentandsimulatebehaviorfromadifferentenvironment.Minimizedcouplingbetweenapplicationblocks.Applicationblocksthataredependentonotherapplicationblockscanencapsulatethisdependencyinaprovider.Thismeansthattheapplicationblockislessvulnerabletorevisionsintheapplicationblockonwhichitdepends.Forexample,theExceptionHandlingApplicationBlockincludestheloggingexceptionhandler.ThishandlerisdependentontheLoggingApplicationBlockandisincludedasaprovider.AnewversionoftheLogging

ApplicationBlockwouldrequireonlyanewlogginghandlerprovider;therestoftheExceptionHandlingApplicationBlockcanremainunchanged.

Forinformationaboutcreatingyourownprovidersfortheapplicationblocks,seethe"ExtendingandModifying"sectionofthedocumentationforeachapplicationblock.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Providers'%0AEntLib50_d24ef321-06d7-480d-8f72-505675b5b021%0APlease provide details of the error you have located...%0A


DesignTimeConfiguration

Allapplicationblocksincludebothrun-timesupportanddesign-timesupportforconfigurationsettings.Therun-timesupportincludesclassesthatrepresenttheconfigurationsettings.TheConfigurationApplicationBlockusestheseclassdefinitionswhenitloadsconfigurationsettings.Itreadstheconfigurationsettingsfromstorageandreturnsobjectsthatcontaintheconfigurationdatatotheapplicationblock.

Thedesign-timeconfigurationsupportincludesclassesthatallowyoutochangetheconfigurationsettingsbyusingtheEnterpriseLibraryconfigurationtools.Theseclassesdefineavisualrepresentationofthedifferentconfigurationsettings,specifytheactionsthatcanbeperformedbasedonthecurrentconfigurationstate,andprovidetheabilitytovalidatetheconfigurationsettings.

Thefollowingfigureillustratestherelationshipbetweentherun-timeconfigurationsupportandthedesign-timeconfigurationsupport.

Thedesign-timeclassesdependontheconfigurationrun-timeclassesbecause

theyobtainthecurrentconfigurationsettingsfromtheconfigurationrun-timeobjects.Whenyouchangethesesettingsandsavethechanges,thedesign-timeobjectsupdatetherun-timeobjects,whicharethensavedinstorage.However,therun-timeclasseshavenodependencyonthedesign-timeclasses.Thereisasinglelightweightdesign-timeassemblythatcontainsdesign-timecoreandsomeblock-specificclasses.Thisisseparatefromtheassembliescontainingtherun-timeimplementations.Thedesign-timeassemblyisnotrequiredforrunninganapplicationthatusestheapplicationblocks.However,itisrequiredwhenyouusetheconfigurationconsoletochangetheconfigurationofanapplicationblock.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design Time Configuration'%0AEntLib50_f963c0b7-904b-467b-80c4-7f20966f0b2c%0APlease provide details of the error you have located...%0A


TheDependencyInjectionModel

ThistopicdescribesthemechanismusedbyEnterpriseLibrarytocreateandmanagethelifetimeofobjectswithinthecoreandtheapplicationblocks.EnterpriseLibraryusesadependencyinjectionmechanismtocreateandmanagethelifetimeofalltheEnterpriseLibraryobjectsitcreates.Dependingonthestyleofyourapplication,itmayusethesamedependencyinjectioncontainerthatEnterpriseLibraryuses.Thistopiccontainsthefollowingsections:

ApplicationandContainerInitializationUsinganAlternativeDependencyInjectionContainerMoreInformation

TolearnhowtousetheUnitydependencyinjectionapproachwhenwritingapplicationcode,seeUsingEnterpriseLibraryinApplications.

ApplicationandContainerInitialization


UsinganAlternativeDependencyInjectionContainer



http://codeplex.com/entlib

http://codeplex.com/entlibcontrib



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Dependency Injection Model'%0AEntLib50_f6e155be-34e9-4f2e-9567-ff222b7afbb2%0APlease provide details of the error you have located...%0A


Instrumentation

InEnterpriseLibrary,theinterfacesandclassesresponsibleforloggingeventstotheWindowsEventLogorupdatingWindowsPerformanceCountersareseparatedfromthosethatindicateaninstrumentation-worthyactivityhasoccurred.

EachapplicationblockcontainsoneormoreclassesresponsiblefortranslatingactivitiesfromwithintheblockintoEventLogmessagesorPerformanceCounterupdates.Theseclassesaregenerallyknownasinstrumentationprovidersbecausetheyprovideinstrumentationserviceswithinthatblock.Classeswithinanapplicationblockusetheinstrumentationproviderstoindicatethatanactivityhasoccurred.

Eachblockisresponsibleforadifferentsetofactivitiesandsotheexactinterfaceoftheprovidervariesforeachblock.Forexample,theinstrumentationproviderinterfacefortheCachingInstrumentationProviderclassisasfollows:C#

publicinterfaceICachingInstrumentationProvider

{

voidFireCacheUpdated(longupdatedEntriesCount,longtotalEntriesCount);

voidFireCacheAccessed(stringkey,boolhit);

voidFireCacheExpired(longitemsExpired);

voidFireCacheScavenged(longitemsScavenged);

voidFireCacheCallbackFailed(stringkey,Exceptionexception);

voidFireCacheFailed(stringerrorMessage,Exceptionexception);

}

TheCacheclassintheCachingBlockusesanICachingInstrumentationProvidereachtimeitmustindicatethecachewasaccessed.WhenthecacheisaccesseditcallstheFireCacheAccessedmethodoftheinstrumentationprovider.

Theinstrumentationprovidersaretypicallyconnectedtootherclasseswithin

theblockthroughaconstructorparameter.TheCacheclass,forexample,takesanICachingInstrumentationProviderasshownhere.C#

publicclassCache:ICacheOperations,IDisposable

{

publicCache(IBackingStorebackingStore,

ICachingInstrumentationProviderinstrumentationProvider)

{

...

}

...

}

Becausetheimplementationsfortheinstrumentationproviderinterfacesareregisteredwithinthedependencyinjectioncontainer,theyareinjectedintotheclassesthatrequirethem.

HowInstrumentationProvidersWorkToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Instrumentation'%0AEntLib50_f8747c05-6255-4911-9b84-7562443d8a2f%0APlease provide details of the error you have located...%0A


GroupPolicySupport

ThisreferencesupplementstheinformationinUsingGroupPolicywithEnterpriseLibrary.Itisdividedintothefollowingsections:

TheManageableConfigurationSourceClass.ThissectiondescribesthedesignoftheclassthatprovidesGroupPolicyconfigurationsupportinEnterpriseLibrary.IntegrationofGroupPolicywithEnterpriseLibraryApplications.ThissectionprovidesinformationabouthowinstancesoftheManageableConfigurationSourceareintegratedwithGroupPolicyandincludesinformationaboutGroupPolicytemplatestructure.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Group Policy Support'%0AEntLib50_cb005873-a57a-4239-9faf-5484e0e729bd%0APlease provide details of the error you have located...%0A


TheManageableConfigurationSourceClass

ThistopicdescribestheclassesthatmakeuptheManageableConfigurationSourceclass.

ManageableConfigurationSource

ManageabilityHelperToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Manageable Configuration Source Class'%0AEntLib50_8acd3afb-6529-403a-b413-2ab8dda05fc0%0APlease provide details of the error you have located...%0A


IntegrationofGroupPolicywithEnterpriseLibraryApplications

TheManageableConfigurationSourceclassreadsconfigurationoverridesfromtheregistryandappliesthoseoverridestoanapplicationconfigurationfile.Byreadingtheregistryinthisway,thisconfigurationsourceallowsyoutouseGroupPolicytospecifythesettings.AGroupPolicytemplatedefinestheconfigurationoptionsforeachapplicationthatisconfiguredinGroupPolicyanddefinesthedefaultoptionsinGroupPolicyforeachconfigurationoption.OneGroupPolicytemplateisrequiredforeachapplicationbecauseaseparateregistrykeyrepresentseachapplication.Thekeyisbasedontheapplicationname.

TosimplifythecreationofGroupPolicytemplates,youcanusetheAdministrativeTemplateGeneratorclasstogenerateanAdmContentobject,andthenwritethiscontenttoastreaminordertogenerateADMfilesfromtheEnterpriseLibraryconfigurationtools.Thesetemplatesusethesettingsdefinedintheapplicationconfigurationfiletodeterminethedefaultsettingsforeachoption.TheyalsodeterminethestructureoftheADMtemplate,whichmustmatchthecontentsoftheconfigurationfile.

InthisversionofEnterpriseLibrary,templatesandGroupPolicysupportareavailableforalltheapplicationblocks,exceptfortheValidationApplicationBlock,thePolicyInjectionApplicationBlock,andUnity.GroupPolicyisafairlystaticandflatmechanism,andtheconfigurationfortheseapplicationblocksisquitedynamicandusuallycomplex.Therefore,itwouldbealmostimpossibletoprovideauseableuserinterfaceimplementationfortheseapplicationblocks.

Note:ApplicationsthatuseGroupPolicytospecifytheirsettingsmustdefineanduseaManageableConfigurationSourceintheconfigurationsourcessection,andsettheEnableGroupPolicyflagonthatsourcetotrue.Youcanusetheconfigurationtoolstoconfigurethissetting.

Thissectioncontainsthefollowingtopics:

GroupPolicyTemplateStructureGeneralSettingsfortheApplicationBlocksExceptionstotheGeneralTemplateStructureApplyingGroupPolicySettingsLimitationsofGroupPolicySupport

GroupPolicyTemplateStructure

http://msdn2.microsoft.com/en-gb/library/aa374150.aspx

GeneralSettingsfortheApplicationBlocks

ExceptionstotheGeneralTemplateStructure

ApplyingGroupPolicySettings

LimitationsofGroupPolicySupportToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Integration of Group Policy with Enterprise Library Applications'%0AEntLib50_ed570525-fc2e-4a9e-b944-91758bb6f72b%0APlease provide details of the error you have located...%0A


UnitTests

EnterpriseLibraryincludesVisualStudio®solutionfilesthatincludeVisualStudioTeamSystemunittestswiththeapplicationblockprojects.YoucanusethemainEnterpriseLibrarysolutionfile(EnterpriseLibrary.VSTS.sln)tobuildtheentireEnterpriseLibrarywiththeunittests.ThissolutioncontainstheentiresetofapplicationblockprojectsandtheEnterpriseLibrarycoreprojects,andincludesallunittestsforexecutionwiththeVisualStudioTeamSystem.

TheEnterpriseLibrarysolutionfilesincludetwobuildconfigurations:ReleaseandDebug.Allprojectswithinasolutionfilearecompiledinbothconfigurations,includingtheunittestprojects.Formoreinformation,seeBuildingEnterpriseLibraryfromtheSourceCode.

Note:ThisreleaseofEnterpriseLibrarydoesnotincludesolutionsthatusetheNUnittestframework.

SoftwareRequirements

Organization

http://msdn2.microsoft.com/en-us/library/7c5ka91b.aspx

UsingtheUnitTestsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://www.microsoft.com/downloads/details.aspx?FamilyID=06616212-0356-46a0-8da2-eebc53a68034&DisplayLang=en


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Unit Tests'%0AEntLib50_07ebea52-f33c-4172-ba66-bce68408946c%0APlease provide details of the error you have located...%0A


TheCachingApplicationBlock

TheEnterpriseLibraryCachingApplicationBlockletsdevelopersincorporatealocalcacheintheirapplications.Itsupportsbothanin-memorycacheand,optionally,abackingstorethatcaneitherbethedatabasestoreorisolatedstorage.TheCachingApplicationBlockcanbeusedwithoutmodification;itprovidesallthefunctionalityneededtoretrieve,add,andremovecacheddata.Configurableexpirationandscavengingpoliciesarealsopartoftheblock.

Note:CachingApplicationBlockfunctionalityisbuiltinto.NETFramework4.0;thereforetheEnterpriseLibraryCachingApplicationBlockwillbedeprecatedinreleasesafter5.0.Youshouldconsiderusingthe.NET4.0System.Runtime.CachingclassesinsteadoftheCachingApplicationBlockinfuturedevelopment.

TheEnterpriseLibraryCachingApplicationBlockincludesthefollowingfeatures:

YoucanusethegraphicalEnterpriseLibraryconfigurationtoolstomanageconfigurationsettings.Youcanconfigureapersistentstoragelocation,usingeitherisolatedstorageortheEnterpriseLibraryDataAccessApplicationBlock,whosestateissynchronizedwiththein-memorycache.AdministratorscanmanagetheconfigurationusingGroupPolicytools.Youcanextendtheblockbycreatingcustomexpirationpoliciesandstoragelocations.Youareassuredthattheblockperformsinathread-safemanner.

ThissectionincludesthefollowingtopicsthatwillhelpyoutounderstandandusetheCachingApplicationBlock:

WhatDoestheCachingApplicationBlockDo?Thistopicprovidesabriefoverviewthatwillhelpyoutounderstandwhattheblockcando,andexplainssomeoftheconceptsandfeaturesitincorporates.Italsoprovidesasimpleexampleofthewaythatyoucanwritecodetousethe

http://msdn.microsoft.com/en-us/library/system.runtime.caching(VS.100).aspx

block.WhenShouldIUsetheCachingApplicationBlock?Thistopicwillhelpyoutodecideiftheblockissuitableforyourrequirements.Itexplainsthebenefitsofusingtheblock,andanyalternativetechniquesyoumayconsider.Italsoprovidesdetailsofanylimitationsoftheblockthatmayaffectyourdecisiontouseit.DevelopingApplicationsUsingtheCachingApplicationBlock.ThistopicfirstexplainshowtoconfiguretheCachingApplicationBlockandaddittoyourapplication.Itthenexplainshowtoselectabackingstore.KeyScenarios.Thissectiondemonstrateshowtousetheblocktoperformtypicalcachingoperations.DesignoftheCachingApplicationBlock.ThistopicexplainsthedecisionsthatwentintodesigningtheCachingApplicationBlockandtherationalebehindthosedecisions.ExtendingandModifyingtheCachingApplicationBlock.Thistopicexplainshowtoextendtheblockbyaddingyourownbackingstoreandyourownexpirationpolicies.Italsoexplainshowtomodifyitbychangingthesourcecode.DeploymentandOperations.ThistopicexplainshowtodeployandupdatetheCachingApplicationBlockassemblies.

MoreInformationForrelatedinformation,seethefollowingpatterns&practicesguidesanddocuments:

MicrosoftApplicationArchitectureGuide,2ndEditionCachingArchitectureGuidefor.NETFrameworkApplicationsEnterpriseLibraryhomepageonMSDN®EnterpriseLibraryontheCodePlexWebsite

Forlinkstoexternalcachingproviders,seethe"MoreInformation"sectioninTheCachingApplicationBlockonMSDN.





http://msdn.microsoft.com/en-us/library/cc467894.aspx

http://www.codeplex.com/entlib



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Caching Application Block'%0AEntLib50_39c7b13a-9654-47bc-93ee-77c48a4ca6cb%0APlease provide details of the error you have located...%0A


WhatDoestheCachingApplicationBlockDo?

TheCachingApplicationBlockprovidesanin-memorycachethatyourapplicationcanmanipulatethroughasimpleAPItostoreandretrieveitems,andtoobtaininformationaboutthestoreditems.Inaddition,youcanconfigureapersistentorcustombackingstoreforyourcache,and—ifrequired—encrypttheinformationstoredthere.Youcanconfiguremorethanonecacheforyourapplication,andspecifyapartitionforeachonesothatdatafrommultiplecachescanbestoredinseparatecontainerswithinthesamebackingstorelocation,suchasadatabase.ThefollowingschematicshowsthemainelementsoftheCachingApplicationBlock.

Atapplicationstartup,theblockloadsthein-memorycachefromthebackingstore(ifconfigured).Alternatively,youcanalsoloadthecacheyourselfifyouwanttoimplementadelayedloadingpattern.Astheapplicationruns,theblockcheckstheexpirationofcacheditemsandremovesthemfromthecache.Expirycanbeconfiguredbasedonslidingorabsolutetimevalues;orthroughdependenciesonfiles,othercacheditems,orexternalresources.Theblockalsomanagesthecacheinconjunctionwithmemoryavailability,basedoncacheditempriorities.

Note:Forinformationaboutthetypesofexpirationyoucanuse,andthedefaultexpirationfornewitems,seeDesignoftheExpirationProcess.

AsapplicationcodeinteractswiththeCacheManager,itupdatesthein-memorycacheand—ifabackingstoreisconfigured—updatesthebackingstore.Youcanconfigureanencryptionproviderforthebackingstore,whichisimplementedbytheCryptographyApplicationBlock,toencrypttheitemsthatarecachedinthebackingstore(notethattheblockdoesnotencryptitemsstoredinthein-memorycache).

TheblockincludesprovidersthatstoredatainadatabaseorinIsolatedStorageonthelocalmachine.Itdoesnotprovideadistributedcachingmechanism.Additionalproviders,includingprovidersthatsupportdistributedcaching,maybeavailablefromthirdpartiesandtheEnterpriseLibrarycommunityWebsite.Formoreinformation,seetheCodePlexCommunityandEnterpriseLibraryContributionsWebsites.



ExampleApplicationCodeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Does the Caching Application Block Do?'%0AEntLib50_906fb004-84fa-462e-8c9f-a7fb1081d679%0APlease provide details of the error you have located...%0A


WhenShouldIUsetheCachingApplicationBlock?

TheCachingApplicationBlockissuitableifyouencounteranyofthefollowingsituations:

Youmustrepeatedlyaccessstaticdataordatathatrarelychanges.Dataaccessisexpensiveintermsofcreation,access,ortransportation.Datamustalwaysbeavailable,evenwhenthesource,suchasaserver,isnotavailable.

YoucanusetheCachingApplicationBlockwithanyofthefollowingapplicationtypes:

WindowsFormsWindowsPresentationFoundation(WPF)WindowsCommunicationFoundation(WCF)ConsoleapplicationWindowsserviceASP.NETWebapplicationorWebserviceifyouneedfeaturesnotincludedintheASP.NETcache

ScenariosfortheCachingApplicationBlock

BenefitsoftheCachingApplicationBlock

LimitationsoftheCachingApplicationBlock

http://msdn.microsoft.com/en-us/library/aa970910.aspx


AlternativestoUsingtheCachingApplicationBlock





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'When Should I Use the Caching Application Block?'%0AEntLib50_7823abac-b4e9-49ce-8798-cd32abb89cb5%0APlease provide details of the error you have located...%0A


DevelopingApplicationsUsingtheCachingApplicationBlock

ThissectiondescribeshowtousetheCachingApplicationBlocktodevelopapplications.Itexplainshowtoenterconfigurationinformationfortheblock,incorporateitintoyoursolution,andselectabackingstore.Thissectionincludesthefollowingtopics:

EnteringConfigurationInformationAddingApplicationCodeSelectingaBackingStore

Allblocksshipasbinaryassembliesandassourcecode.Ifyouwanttousethesourcecode,youmustcompileit.TolearnhowtocompiletheEnterpriseLibrarysourcecode,seeBuildingEnterpriseLibraryfromtheSourceCode.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Developing Applications Using the Caching Application Block'%0AEntLib50_e059d319-04df-45f2-a560-443fb055c6fc%0APlease provide details of the error you have located...%0A


EnteringConfigurationInformation

TheseproceduresexplainhowtoconfiguretheCachingApplicationBlock.IfyouaddaDatabaseCacheStorageprovidertotheconfigurationoftheCachingApplicationBlock,theconfigurationtoolautomaticallyaddstheDataAccessApplicationBlock.YoumustconfigurethatblockbeforeyouconfiguretheDatabaseCacheStorageproviderintheCachingApplicationBlockconfiguration.

FordetailsoftheschemafortheCachingApplicationBlockconfiguration,seeSourceSchemafortheCachingApplicationBlock.Youcanalsoconfiguretheblockincodebyusinganalternateconfigurationsource.Formoreinformation,seeAdvancedConfigurationScenariosandUsingtheFluentConfigurationAPI.

ToaddtheCachingApplicationBlock1. Opentheconfigurationfile.Formoreinformation,seeConfiguring

EnterpriseLibrary.2. OpentheBlocksmenuandthenclickAddCachingSettings.3. TheconfigurationtoolautomaticallyaddstheCachingSettingssection

withdefaultvalues,andadefaultCacheManageritem.

Toconfigurecachemanagers1. ClickthepropertiesexpanderarrowintheCachingSettingssectionto

openthelistofproperties.2. (Optional)ChangetheDefaultCacheManagerpropertyname.The

defaultcachemanagerisusedifthecodedoesnotspecifyacachemanager.Eitherenteranewnameorselectonefromthedrop-downlist.ThedefaultnameisCacheManager.

3. (Optional)Ifyouwanttoencrypttheconfiguration,makeaselectionfromtheProtectionProviderdrop-downlist.YoucanselecttheRsaProtectedConfigurationProviderortheDataProtectedConfigurationProvider.SeeEncryptingConfigurationDataforinformationabouttherestrictionsonusingtheRsaProtectedConfigurationProvider.

4. (Optional)Ifyouwanttorunyourapplicationinpartialtrustmode,changetheRequirePermissionpropertytoFalse.ThedefaultisTrue.

5. ToaccessthedefaultCacheManagerproperties,clickthesection

expanderarrowtotheleftofthedefaultCacheManagertitle.Ifyourenamedthecachemanager,thetitlewillbethenameyouassignedit.

6. (Optional)RenametheCacheManagernode.ThedefaultnameisCacheManager.

7. (Optional)SettheBackingStoreproperty.Thedefaultis<none>whichmeansthatthecachemanageronlystoresdatainmemory.Thedrop-downlistshowsyoutheavailablebackingstoresyoucanchoosefrom.YoucanaddbackingstoresintheBackingStorespane.

8. (Optional)SettheNumbertoRemovewhenScavengingproperty.Thisisthenumberofelementstoremoveafterscavengingbegins.Thedefaultsettingis10elements.

9. (Optional)SettheMax.ElementsinCacheBeforeScavengingproperty.Thisisthemaximumnumberofelementsthatcanbeinthecachebeforescavenging.Thedefaultsettingis1000elements.

10. (Optional)SettheExpirationPollingFrequencyproperty.Thisisthefrequencyofthetimerthatregulateshowoftenthebackgroundschedulerchecksforexpireditems.Theunitisseconds,andthedefaultsettingis60.

Bydefault,thecachestoresitemsonlyinmemoryandassignsthevalueofthe

backingstoretoNullBackingStore.YoucanaddcachingstoresandthenconfiguretheCachingApplicationBlocktouseanyofthestoresyouhaveadded.YoucanconfiguretheCachingApplicationBlocktousedatabasecachestorage,isolatedstorage,orcustomcachestorage.DatabasecachestorageusestheDataAccessApplicationBlock.

ToadddatabasecachestorageandconfiguretheCachingApplicationBlocktouseit

1. ClicktheplussigniconintheBackingStorespane,pointtoAddBackingStoresandclickAddDataCacheStorage.

2. TheconfigurationtoolautomaticallyaddstheDatabaseSettingssection.Forinformationaboutconfiguringthissection,seeTheDataAccessApplicationBlockdocumentation.

3. ClickthepropertiesexpanderarrowinthenewDataCacheStoragesectiontoopenthelistofproperties.

4. (Optional)SettheNamepropertybyrenamingtheDataCacheStoragenode.

5. SettheDatabaseInstancepropertybymakingaselectionfromthetextboxdrop-downlist.Thisisthenameofthedatabaseconnectionstring.ItmustcorrespondtothenameofaconnectionstringintheDatabaseSettingssection.

6. Ifyouwanttoencrypttheinformationstoredinthedatabase,youmusthaveconfiguredanencryptionprovider.Toaddanewencryption

provider,clicktheplussigniconintheEncryptionProviderspaneoftheCachingSettingssection,pointtoAddEncryptionProvidersandthenclickAddSymmetricCryptoProvider(thisistheonlyencryptionprovideroffered).TheconfigurationtoolautomaticallyaddstheCryptographySettingssection.

7. IntheCryptographySettingssection(nottheCachingSettingssection),addasymmetriccryptographyprovidertotheconfiguration.Forinformationaboutconfiguringthisblock,seeTheCryptographyApplicationBlockdocumentation.

8. IntheCachingSettingssection,selectthenewsymmetricencryptionprovideryouconfiguredintheCryptographySettingssectionoranexistingencryptionproviderinthatsection,inthedrop-downlistfortheSymmetricCryptoProviderproperty.

9. IntheBackingStorespane,intheDataCacheStoragesection,settheEncryptionProviderpropertybyselectingtheSymmetricCryptoProvideritemyoujustconfigured.

10. IntheCacheManagerssection,selectthenewbackingstoreyouaddedinthedrop-downlistfortheBackingStorepropertyofthecachemanagerthatwillusethisbackingstore.

ToaddisolatedstorageandconfiguretheCachingApplicationBlocktouseit

1. ClicktheplussigniconintheBackingStorespane,pointtoAddBackingStoresandclickAddIsolatedStorageCacheStore.

2. (Optional)InthenewIsolatedStorageCacheStoresection,settheNameproperty.

3. SetthePartitionNameproperty.Thisidentifiestheportionofisolatedstoragethatthecachemanagerwilluse.

4. Ifyouwanttoencrypttheinformationstoredinisolatedstorage,youmusthaveconfiguredanencryptionprovider.Toaddanewencryptionprovider,clicktheplussigniconintheEncryptionProviderspaneoftheCachingSettingssection,pointtoAddEncryptionProvidersandthenclickAddSymmetricCryptoProvider(thisistheonlyencryptionprovideroffered).TheconfigurationtoolautomaticallyaddstheCryptographySettingssection.

5. IntheCryptographySettingssection(nottheCachingSettingssection),addasymmetriccryptographyprovidertotheconfiguration.

Forinformationaboutconfiguringthisblock,seeTheCryptographyApplicationBlockdocumentation.

6. IntheCachingSettingssection,selectthenewsymmetricencryptionprovideryouconfiguredintheCryptographySettingssectionoranexistingencryptionproviderinthatsection,inthedrop-downlistfortheSymmetricCryptoProviderproperty.

7. IntheBackingStorespane,intheIsolatedStorageCacheStoresection,settheEncryptionProviderpropertybyselectingtheSymmetricCryptoProvideritemyoujustconfigured.

8. IntheCacheManagerssection,selectthenewbackingstoreyouaddedinthedrop-downlistfortheBackingStorepropertyofthecachemanagerthatwillusethisbackingstore.

Toaddacustomcachestorageprovider1. ClicktheplussigniconintheBackingStorespane,pointtoAdd

BackingStoresandclickAddCustomCacheStorage.2. TheTypeSelectordialogisdisplayed.Navigatetotheassembly

containingyourcustombackingstoreandclickonit.ThestorewillbeaddedanddisplayedintheBackingStorespane.

3. (Optional)Inthenewcustomstoresection,settheNameproperty.4. Ifthecustombackingstorerequiresanyotherconfigurationvaluesto

beprovided,addtheseaskey/valuepairstotheconfigurationbytypingthemintotheKeyandValuetextboxes.Asyouenteravalue,theconfigurationtooldisplaysanewrowinthissection.Clickthecrossbuttontoremoveaname/valuepair.

Ifyouwanttoaddanothercachemanagertoyourapplicationconfiguration,clicktheplussigniconintheCacheManagerspane,pointtoAddCacheManagersandthenclickonthemanageryouwishtoadd.Repeattheprecedingprocedures.Therecanbeonlyonedefaultcachemanager.Eachinstanceofthecachemanagermusthaveauniquename.

UsageNotesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Entering Configuration Information'%0AEntLib50_9805bcb6-f6bf-44ae-8bbc-674fe3e6642a%0APlease provide details of the error you have located...%0A


SourceSchemafortheCachingApplicationBlock

ThistopicliststheXMLelementsandattributesusedtoconfiguretheCachingApplicationBlock.YoucanmanuallyedittheXMLdata,buttheEnterpriseLibraryconfigurationtoolsgreatlysimplifythistask.IfyouchoosetomanuallyedittheXML,usetheschemainformationcontainedinthistopic.

Theconfigurationfilehasthefollowingsectionhandlerdeclaration.XML

<configSections>

<sectionname="cachingConfiguration"

type="Microsoft.Practices.EnterpriseLibrary.Caching.Configuration.CacheManagerSettings,

Microsoft.Practices.EnterpriseLibrary.Caching"/>

</configSections>

Thesectionhandlerdeclarationcontainsthenameoftheconfigurationsettingssectionandthenameofthesectionhandlerclassthatprocessesconfigurationdatainthatsection.ThenameoftheconfigurationsettingssectioniscachingConfiguration.ThenameofthesectionhandlerclassisMicrosoft.Practices.EnterpriseLibrary.Caching.Configuration.CacheManagerSettings

cachingConfigurationElement

encryptionProvidersElement

backingStoresElement

cacheManagersElement




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Source Schema for the Caching Application Block'%0AEntLib50_66f57cad-ca40-41d4-97ca-4685c3b3ec3a%0APlease provide details of the error you have located...%0A


AddingApplicationCode

TheCachingApplicationBlockisdesignedtosupportthemostcommonsituationsforstoringdatainacache.Whenaddingyourapplicationcode,refertothescenariosintheKeyScenariossectionsandselecttheonesthatbestsuityoursituation.Usethecodethataccompaniesthescenarioeitherasitis,orreviseitasrequired.

Toprepareyourapplication1. AddareferencetotheCachingApplicationBlockassembly.In

MicrosoftVisualStudio®,right-clickyourprojectnodeinSolutionExplorer,andthenclickAddReference.ClicktheBrowsetabandfindthelocationoftheMicrosoft.Practices.EnterpriseLibrary.Caching.dllassembly.Selecttheassembly,andthenclickOKtoaddthereference.

2. Followthesameproceduretosetareferencetothefollowingassemblies:

Microsoft.Practices.EnterpriseLibrary.Common.dllMicrosoft.Practices.ServiceLocation.dllMicrosoft.Practices.Unity.dllMicrosoft.Practices.Unity.Interception.dll

3. Ifyouareusingthedatabasebackingstore,addareferencetoMicrosoft.Practices.EnterpriseLibrary.Caching.Database.dllandMicrosoft.Practices.EnterpriseLibrary.Data.dll.

4. IfyouareusingtheCryptographyApplicationBlocktoencryptdatainthecache,addreferencestoMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography.dllandMicrosoft.Practices.EnterpriseLibrary.Caching.Cryptography.dll.

5. (Optional)TouseelementsfromtheCachingApplicationBlockwithoutfullyqualifyingtheelementreference,addthefollowingusingstatements(C#)orImportsstatements(MicrosoftVisualBasic®)tothetopofyoursourcecodefile.C#

usingMicrosoft.Practices.EnterpriseLibrary.Caching;

usingMicrosoft.Practices.EnterpriseLibrary.Caching.Expirations;

VisualBasic

ImportsMicrosoft.Practices.EnterpriseLibrary.Caching

ImportsMicrosoft.Practices.EnterpriseLibrary.Caching.Expirations

Note:ForVisualBasicprojects,youcanalsousetheReferencespageoftheProjectDesignertomanagereferencesandimportednamespaces.ToaccesstheReferencespage,selectaprojectnodeinSolutionExplorer,andthenclick[projectname]PropertiesontheProjectmenu.WhentheProjectDesignerappears,clicktheReferencestab.

Next,addtheapplicationcode.Generally,therearetwostepstocreatecodethatusestheCachingApplicationBlock:

1. ResolveaCacheManagerinstance.2. Calltheappropriatemethods.

Eachkeyscenariodemonstrateshowtoincorporatethesestepsintoanapplication.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Application Code'%0AEntLib50_6da7b6ad-3295-468d-9202-df6daca525c2%0APlease provide details of the error you have located...%0A


SelectingaBackingStore

Eachcachemanagercanbeconfiguredtostoredataonlyinmemory,whichmeansthatitusesthenullbackingstore,oreachcachemanagercanbeconfiguredtostoredatabothinmemoryandinpersistentstorage.Thetypeofpersistentstorageisspecifiedwhenyouconfigurethebackingstore.Backingstoresletcacheddatasurviveiftheapplicationmustberestarted.Initsoriginalstate,theCachingApplicationBlocksupportstwotypesofpersistentbackingstores,eachofwhichissuitedtoparticularsituations:

Isolatedstorage–seeUsingtheIsolatedStorageBackingStore.Databasecachestorage–seeUsingtheDataAccessApplicationBlockBackingStore.

Ifyouintendtoperformcachinginamultiple-serverenvironment,suchasaWebfarm,seeConsiderationsforServerScenarios.

Toprotectexternaldatastoresfromunauthorizedaccess,considerthislistofUsageNotes.

DeveloperscanextendtheCachingApplicationBlocktosupportadditionaltypesofbackingstores.Formoreinformationaboutthistopic,seeExtendingandModifyingtheCachingApplicationBlock.

Note:Anapplicationcanusemorethanonecache;eachcachewillberepresentedbyacachemanagerintheapplication'sconfiguration.TheCachingApplicationBlockdoesnotsupporttheuseofthesamepersistentbackingstorelocationbymultiplecachemanagersinanapplication.However,multiplecachemanagersinanapplicationcanhavethesamepartitionname.

UsageNotes



UsingtheNullBackingStore

UsingtheIsolatedStorageBackingStore

http://msdn.microsoft.com/en-us/library/kbcw921f.aspx

UsingtheDataAccessApplicationBlockBackingStore

ConsiderationsforServerScenarios




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Selecting a Backing Store'%0AEntLib50_9b5f7ac7-b6de-4d4b-b22d-5b70747ef88f%0APlease provide details of the error you have located...%0A


KeyScenarios

Thissectiondescribesthemostcommonsituationsdevelopersmustaddresswhenstoringdatainacache.Eachscenarioexplainsthetask,givesareal-worldsituationforthetask,andincludescodedemonstratinghowtousetheCachingApplicationBlocktocompletethetask.

AddingItemstotheCache.ThistopicdescribesthebasiccachingoperationssuchashowtoaddanitemtothecacheusingtheAddmethod,settingtheitem'sexpirationpolicy(fortheexpirationprocess)anditspriority(forthescavengingprocess).RemovingItemsfromtheCache.ThistopicdescribeshowtoremoveanitemfromthecacheusingtheRemovemethod.RetrievingItemsfromtheCache.ThistopicdescribeshowtoobtainanitemfromthecacheusingtheGetDatamethod.FlushingtheCache.Thistopicdescribeshowtoflushthecache,whichemptiesit,usingtheFlushmethod.LoadingtheCache.Thistopicdemonstratesproactiveandreactiveloading.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Key Scenarios'%0AEntLib50_cd901b95-0339-43be-8376-60a809b982f2%0APlease provide details of the error you have located...%0A


AddingItemstotheCache

Cachesstoreitemsthatareeitherexpensivetocreateorexpensivetotransport.Forexample,inaretailapplication,alistofproductsmustbepassedfromthedataaccesscomponentstotheuserinterfacecomponentssothattheproductlistcanbedisplayedtotheusers.Thedatarepresentsreal-worldbusinessentities,suchasproductsororders.Toincreaseperformance,someoftheseitemsmaybeaddedtothecache.

TypicalGoals

Solution

UsingtheAddMethod

RefreshingRemovedItems





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Items to the Cache'%0AEntLib50_a2b5be4d-d4e7-4db7-a068-3dd8c4344bfb%0APlease provide details of the error you have located...%0A


RemovingItemsfromtheCache

Thescavengingandexpirationprocessesautomaticallyremoveitemsfromthecacheaccordingtotheprioritiesandexpirationpoliciesoftheitems.Youcanalsoremovespecificitemsfromthecache.Forexample,inaretailapplication,somedatamaynolongerbeapplicable,dependingonselectionsthecustomermakes.

TypicalGoals

Solution

UsingtheRemoveMethodToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Removing Items from the Cache'%0AEntLib50_ada48e02-08e2-48e3-8518-7e10955b1c2f%0APlease provide details of the error you have located...%0A


RetrievingItemsfromtheCache

Datastoredinthecachemustberetrievedsothatitcanbedisplayedorprocessed.Forexample,inaretailapplication,youmaywanttodisplayalistofproductsfromacatalog.

TypicalGoals

Solution

UsingtheGetDataMethodToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Retrieving Items from the Cache'%0AEntLib50_7f6ac31c-8a58-4403-9c77-79595bdc0cc9%0APlease provide details of the error you have located...%0A


FlushingtheCache

Flushingletsyoumanagecacheditemstomakesurethatstorage,memory,andotherresourcesareusedefficiently.Flushingremovesallitemsinthecache,includingthosethathavenotyetexpired.Forexample,inaretailapplication,cacheddatamaynolongerbevalidbecauseofselectionsmadebythecustomerorbecausethecustomerhasloggedoff.

TypicalGoals

Solution

UsingtheFlushMethodToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Flushing the Cache'%0AEntLib50_34e6f0b6-41bd-4dee-996d-00466059737b%0APlease provide details of the error you have located...%0A


LoadingtheCache

Beforeyoucanusecacheddata,youmustfirstloaddataintothecache.Forexample,inaretailapplication,youmaywanttoloaddataaboutvariousproducts,orallproducts,intothecache.

TypicalGoals

Solution

CachingDataProactively

CachingDataReactively


LoadingExamplesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Loading the Cache'%0AEntLib50_295f8fbd-d4e2-4bfd-9784-7b1f95363e2a%0APlease provide details of the error you have located...%0A


DesignoftheCachingApplicationBlock

TheCachingApplicationBlockisdesignedspecificallysothat:ItprovidesasetofAPIsthataremanageableinsize.Itenablesdeveloperstoincorporatethestandardcachingoperationsintotheirapplicationswithouthavingtolearntheinternalworkingsoftheblock.ItusestheEnterpriseLibraryconfigurationtoolsforeasyconfiguration.Itperformsefficiently.Itisthreadsafe.Codeisconsideredtobethreadsafewhenitcanbecalledfrommultipleprogrammingthreadswithoutunwantedinteractionamongthosethreads.Itensuresthatthebackingstoreremainsintactifanexceptionoccurswhileitisbeingaccessed.Itensuresthatthestatesofthein-memorycacheandthebackingstoreremainsynchronized.

Thistopicdescribesthedesignofthecachingsystem,describingthehighlightsandspecificdesigndetails.OthertopicsinthissectionincludeDesignoftheExpirationProcessandDesignoftheScavengingProcess.

DesignHighlights

DesignDetailsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Caching Application Block'%0AEntLib50_5e0848c4-aa5d-4921-9a92-75cb8377fbab%0APlease provide details of the error you have located...%0A


DesignoftheExpirationProcess

TheCachingApplicationBlock'sexpirationprocessisperformedbytheBackgroundScheduler.Itperiodicallyexaminesthecacheditemsinthehashtabletoseeifanyitemshaveexpired.YoucontrolhowfrequentlytheexpirationcycleoccurswhenyouconfigureaninstanceoftheICacheManagerinterfacedefaultimplementationCacheManagerbyusingtheconfigurationtools.

TheexpirationpoliciesprovidedwiththeCachingApplicationBlockarethese:Absolute.Thismeanstheitemexpiresataspecifictime.Sliding.Thismeanstheitemexpiresafterthespecifiedtimehaselapsedfromwhentheitemwaslastaccessed.Thedefaulttimeis2minutes.Extendedformat.Thisallowsyoutospecifyverydetailedexpirationconditions.Forexample,youcanspecifythatanitemexpireseverySaturdaynightat10:03PMoronthethirdTuesdayofeachmonth.ExtendedformatsarelistedintheExtendedFormat.csfile.Filedependency.Thismeanstheitemexpireswhenaspecificfileismodified.Neverexpired.Thismeanstheitemwillneverexpire,althoughitmaystillberemovediftheblockdetectsalackofavailablememory.

Thefirstthreepolicies,absolute,sliding,andextendedformat,arereferredtoastime-basedexpirations.Youshouldusetime-basedexpirationforvolatilecacheitems,suchasthosethathaveregulardatarefreshesorthosethatarevalidforonlyaspecifiedtime.Time-basedexpirationletsyousetpoliciesthatkeepitemsinthecacheonlyaslongastheirdataremainscurrent.Forexample,ifyouarewritinganapplicationthattrackscurrencyexchangeratesbyobtainingthedatafromafrequentlyupdatedWebsite,youcancachethecurrencyratesforthetimethatthoseratesremainconstantonthesourceWebsite.Inthissituation,youwouldsetanexpirationpolicythatisbasedonthefrequencyoftheWebsiteupdates.

Thefourthpolicy,filedependency,isreferredtoasanotification-basedexpiration.Itdefinesthevalidityofacacheditembasedonaparticularfile.Ifthefileismodified,thecacheditemisinvalidatedandremovedfromthecache.

TheAddmethodhastwooverloads.Oneoverloadassumesthedefault

expirationpolicy,whichisNeverExpired.Theotheroverloadletsyousettheexpirationpoliciesyourself.Youcanuseasmanypoliciesasyouwant,includingpoliciesthatyoucreateyourself.(FormoreinformationaboutextendingtheCachingApplicationBlockbyaddingyourownexpirationpolicies,seeExtendingandModifyingtheCachingApplicationBlock.)Ifyouhaveanitemwithmultiplepolicies,theitemwillexpireifanyoneofthepolicy'scriteriaismet.

MarkingandSweeping

CallbacksToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Expiration Process'%0AEntLib50_9861aeec-729f-4e54-9a73-86574a0bc80f%0APlease provide details of the error you have located...%0A


DesignoftheScavengingProcess

TheCachingApplicationBlock'sscavengingprocessisperformedbytheBackgroundSchedulerobject.Itchecksthecacheeverytimeanitemisaddedtoseeifthenumberofitemsinthecachehasreachedapredeterminedlimit.Youusetheconfigurationtoolstosetthislimitwhenyouconfigureaninstanceofacachemanager.Youalsosethowmanyitemsareremovedfromthecacheafterscavengingbegins.

Whenanitemisaddedtothecache,thecodecansetoneoffourprioritysettings:Low,Normal,High,orNotRemovable.TheBackgroundSchedulerobjectdetermineswhichitemsshouldbescavengedbydoingamajorsortbasedonpriorityandaminorsortbasedonthelasttimetheitemwasaccessed.Forexample,anitemwithaLowprioritythathasjustbeenusedwillbescavengedbeforesomethingwithaHighprioritythathasnotbeenaccessedforthreeyears.ThedefaultvalueisNormal.

TheNotRemovablepriorityisusedwhenyouwantanitemtoremaininthecacheuntilitexpires.However,thecacheshouldnotbeusedastheonlylocationwhereanitemofdataexists.Acacheshouldbeusedtoimproveperformance;itshouldnotbeusedasaformofpermanentstorage.

Unliketheexpirationprocess,thescavengingprocessperformsmarkingandsweepinginasinglepass.Formoreinformationaboutmarkingandsweeping,seeDesignoftheExpirationProcess.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Scavenging Process'%0AEntLib50_55e9cb69-0c47-4e6d-98a1-9702656594cf%0APlease provide details of the error you have located...%0A


ExtendingandModifyingtheCachingApplicationBlock

Initsoriginalstate,theCachingApplicationBlockworkswellfortypicalcachingsituations.However,theremaybetimeswhenyouhavetocustomizesomeoftheblock'sbehaviortobettersuityourapplication'sparticularrequirements.Therearetwowaystodothis.YoucanextendtheCachingApplicationBlockusingthebuilt-inextensionpoints.Youcanalsomodifytheblockbymakingchangestoitssourcecode.Formoredetails,seethefollowingtopics:

ExtendingtheCachingApplicationBlockExtendingandModifyingEnterpriseLibrary




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying the Caching Application Block'%0AEntLib50_ec8dd8fc-453b-4313-8056-242813d4fc3e%0APlease provide details of the error you have located...%0A


ExtendingtheCachingApplicationBlock

Youextendtheblockthroughdesignatedextensionpoints.Typically,thesearecustomclasses,writtenbyyou,thatimplementaparticularinterfaceorderivefromanabstractclass.Becausethesecustomclassesexistinyourapplicationspace,youdonothavetomodifyorrebuildtheblock.Instead,youdesignateyourextensionsusingconfigurationsettings.

Youcanextendtheblockbyaddinganewtypeofbackingstoreandstorageencryptionprovider,byaddingnewexpirationpolicies,orbyreplacingthedefaultCacheManager.Thefollowingtableliststheinterfacesandbaseclassesthatyoucanusetoextendtheblock.

CustomProviderorExtension InterfaceorBaseClass

BackingStore IBackingStoreorBaseBackingStore

CacheManager ICacheManager

ExpirationPolicy ICacheItemExpiration

StorageEncryptionProvider IStorageEncryptionProvider

FordetailedinformationabouthowtointegratecustomproviderswiththeEnterpriseLibraryconfigurationsystemandconfigurationtoolsseeCreatingCustomProvidersforEnterpriseLibrary.

AddingaNewBackingStore

AddingaNewExpirationPolicy

ReplacingtheDefaultCacheManagerToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending the Caching Application Block'%0AEntLib50_78f99a1c-9b1d-4c68-a393-a905c8df0b9d%0APlease provide details of the error you have located...%0A


DeploymentandOperations

Twoofanadministrator'smaintaskswillbetomakesurethattheinitialdeploymentoftheCachingApplicationBlockisplannedandmanagedandtomakesurethatsubsequentupdatesaredeployedwithminimalimpacttoexistingapplicationsthatusetheblock.FordetailsofdeployingandupdatingEnterpriseLibraryandtheblocks,seeDeployingEnterpriseLibrary.

Inaddition,administratorsmustdecidewhethertheywanttousetheinstrumentationexposedbytheblock.Fordetailsofhowtoenableanddisableinstrumentation,seeEnablingInstrumentation.ForinformationabouttheinstrumentationcontainedwithintheCachingApplicationBlock,seethefollowingtopics:

CachingApplicationBlockPerformanceCountersCachingApplicationBlockEventLogEntries




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deployment and Operations'%0AEntLib50_2480c226-9e87-44a1-84e6-97968d1c428a%0APlease provide details of the error you have located...%0A


CachingApplicationBlockPerformanceCounters

ThefollowingtabledescribestheCachingApplicationBlockperformancecounters.

PerformanceCounter

Description

CacheExpiries/sec

Therateatwhichitemswereexpiredfromthecache.

CacheHitRatio Theratioofcachehitstoreads.Acachehitoccurswhenthecachecontainstherequesteditem.

CacheHits/sec Therateatwhichthecachereceivedrequestsforitemsitcontained.

CacheMisses/sec Therateatwhichthecachereceivedrequestsforitemsitdidnotcontain.

CacheScavengedItems/sec

Therateatwhichitemswerescavengedfromthecache.

Total#ofCacheAccessAttempts

Thetotalnumberofreadsfromthecache.

TotalCacheEntries

Thetotalnumberofitemsinthecache.

TotalCacheExpiries

Thetotalnumberofitemsexpiredfromthecache.

TotalCacheHits Thetotalnumberofrequestsforexistingitemsreceivedbythecache.

TotalCacheMisses

Thetotalnumberofrequestsfornon-existingitemsreceivedbythecache.

TotalCacheScavengedItems

Thetotalnumberofitemsscavengedfromthecache.

TotalUpdated Thetotalnumberofitemsupdatedinthecache.An

Entries updatecanbeeitheran"add"ora"remove"action.

UpdatedEntries/sec

Therateatwhichitemsinthecachewereupdated.Anupdatecanbeeitheran"add"ora"remove"action.

Aratecountersamplesanincreasingcountofeventsovertimeanddividesthevaluesbythechangeintimetodisplayarateofactivity.Formoreinformationaboutperformancecounters,seeOverviewofPerformanceMonitoringinthe.NETFrameworkClassLibraryonMSDN.



http://technet.microsoft.com/en-us/library/cc958260.aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Caching Application Block Performance Counters'%0AEntLib50_6f99b7f6-e746-4218-a53d-7d84f37f99d6%0APlease provide details of the error you have located...%0A


CachingApplicationBlockEventLogEntries

ThistopicliststheCachingApplicationBlockeventlogentries.Thelisteneristheclassthatraisedtheevent.

CacheFailedEvent

CacheCallbackFailedEvent

ConfigurationErrorEvent

ConfigurationChangedEventToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Caching Application Block Event Log Entries'%0AEntLib50_82ea7e9a-51ef-4767-9731-23689cd66375%0APlease provide details of the error you have located...%0A


TheCryptographyApplicationBlock

Developersfrequentlywriteapplicationsthatrequireencryptionandhashingcapabilitiestomeetthesecurityrequirementsoftheirorganization.Datathatiscreatedandmaintainedbyapplications,aswellasconfigurationinformation,oftenneedstobeencrypted.Additionally,passwordsthatareusedtoaccessapplicationfunctionalityordataneedtobehashed.

TheEnterpriseLibraryCryptographyApplicationBlocksimplifiesthewaydevelopersincorporatecryptographicfunctionalityintheirapplications.Applicationscanusetheblockforavarietyoftasks,suchasencryptinginformation,creatingahashfromdata,andcomparinghashvaluestoverifythatdatahasnotbeenaltered.Inaddition,youcanchangetheunderlyingprovidersthroughconfigurationwithoutchangingtheunderlyingapplicationcode.

TheCryptographyApplicationBlockincludessupportforthefollowingfeatures:

EncryptionalgorithmsHashingalgorithmsMultiplecryptographyprovidersAdditionalimplementationsofcryptographyprovidersKeyprotectionwiththedataprotectionAPI(DPAPI)

ThissectionincludesthefollowingtopicsthatwillhelpyoutounderstandandusetheCryptographyApplicationBlock:

WhatDoestheCryptographyApplicationBlockDo?Thistopicprovidesabriefoverviewthatwillhelpyoutounderstandwhattheblockcando,andexplainssomeoftheconceptsandfeaturesitincorporates.Italsoprovidesasimpleexampleofwritingcodetousetheblock.WhenShouldIUsetheCryptographyApplicationBlock?Thistopicwillhelpyoutodecideiftheblockissuitableforyourrequirements.Itexplainsthebenefitsofusingtheblock,andanyalternativetechniquesyoumayconsider.Italsoprovidesdetailsofanylimitationsoftheblockthatmayaffectyourdecisiontouseit.DevelopingApplicationsUsingtheCryptographyApplicationBlock.ThistopicdescribeshowtoinstalltheCryptographyApplicationBlocksothatyoucanuseitinyourapplications.Italsodescribeshowto

configuretheblockforcommonoperations.KeyScenarios.Thistopicthenshowshowtousetheblocktoperformmostcryptographytasks.DesignoftheCryptographyApplicationBlock.Thistopicexplainsthedecisionsthatwentintothedesignoftheblockandtherationalebehindthosedecisions.ExtendingandModifyingtheCryptographyApplicationBlock.ThistopicexplainshowtoextendtheCryptographyApplicationBlockbycreatingyourownprovidersandhowtomodifythesourcecode.DeploymentandOperations.Thistopicexplainshowtodeployandupdatetheblock'sassemblies.Italsocontainsinformationaboutconfiguration.

MoreInformationFormoreinformation,seethefollowingresources:

ImprovingWebApplicationSecurity:ThreatsandCountermeasuresHowTo:UseAuthorizationManager(AzMan)withASP.NET2.0patterns&practicesSecurityHowToIndex







mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Cryptography Application Block'%0AEntLib50_3df31134-670c-4d8b-a42f-18535233a883%0APlease provide details of the error you have located...%0A


WhatDoestheCryptographyApplicationBlockDo?

TheCryptographyApplicationBlockconsistsofafacadethatallowsyoutoaccessthetwotypesofproviderscontainedwithintheblock.Thesetwotypesofprovidersare:

Hashingproviders.Theseproviderscanbeusedtogenerateahashfromavalueyousupply,andcomparetwohashvalues.Theblockincludeshashprovidersthatusearangeofcommonhashingalgorithms.Cryptographyproviders.Theseproviderscanbeusedtoencryptanddecryptvaluesthatyousupply.Theblockincludescryptographyprovidersthatusearangeofcommonencryptionalgorithms.

Whenyouusethecryptographyproviderstoencryptavalue,youcanspecifythevalueasanarrayofbytes,andthemethodwillreturntheresultasanarrayofbytes.Alternatively,youcanspecifytheinputvalueasastring,andthemethodswillreturntheresultasabase-64encodedstring.Themethodsthatdecryptvaluesworkthesameway,exceptthatstringvaluesreturnedbythemethodsarenotbase-64encoded.

Whenyouusethehashingproviderstocreateahash,youcanspecifythevaluetohashasanarrayofbytes,andthemethodwillreturntheresultasanarrayofbytes.Alternatively,youcanspecifytheinputvalueasastring,andthemethodswillreturntheresultasastring.Themethodsthatcomparehashvaluesaccepteitheranarrayofbytesorastring,andreturneithertrueorfalse.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Does the Cryptography Application Block Do?'%0AEntLib50_7b92a72e-a4c1-46bf-908c-45720ecf88bb%0APlease provide details of the error you have located...%0A


WhenShouldIUsetheCryptographyApplicationBlock?

YoushouldusetheCryptographyApplicationBlockwhenyouneedhashingand/orsymmetricencryptionfunctionality.Youcanusethesefunctionsinconjunctionwiththecryptographicprovidersincludedwiththeblockorwithyourowncustomcryptographicproviders.Ifthedataonlyneedstobeencrypted,anditdoesnotneedtobedecrypted(forexample,apassword),youcanusehashing.Ifthedataneedstobebothencryptedanddecrypted(forexample,totransmitsensitivecustomerdata),youcanusesymmetricencryption.

ScenariosfortheCryptographyApplicationBlock

BenefitsoftheCryptographyApplicationBlock

LimitationsoftheCryptographyApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'When Should I Use the Cryptography Application Block?'%0AEntLib50_c3784e04-cbf1-4e78-9ee4-89442263ae55%0APlease provide details of the error you have located...%0A


DevelopingApplicationsUsingtheCryptographyApplicationBlock

ThistopicdescribeshowtodevelopapplicationsusingtheCryptographyApplicationBlock.Itexplainshowtomodifytheconfigurationoftheblocktoperformparticulartasksandhowtousetheblockforparticularscenarios,suchasencryptingdata.Thistopicassumesthatyouareusingtheblockinitsoriginalstate,withoutextendingit.(Tolearnhowtoaddfunctionality,seeExtendingandModifyingtheCryptographyApplicationBlock.)Thissectionincludesthefollowingtopics:

EnteringConfigurationInformationAddingApplicationCode

Allapplicationblocksshipasbinaryassembliesandassourcecode.Ifyouwanttousethesourcecode,youmustcompileit.TolearnhowtocompiletheEnterpriseLibrarysourcecode,seeBuildingEnterpriseLibraryfromtheSourceCode.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Developing Applications Using the Cryptography Application Block'%0AEntLib50_8decc496-e19a-473d-8aae-d9aae9e7acb3%0APlease provide details of the error you have located...%0A



TheseproceduresexplainhowtoconfiguretheCryptographyApplicationBlock.AlsoseeUsingtheCryptographicKeyWizard.Fordetailsoftheconfigurationschema,seeSourceSchemafortheCryptographyApplicationBlock.Youcanalsoconfiguretheblockincodebyusinganalternateconfigurationsource.Formoreinformation,seeAdvancedConfigurationScenariosandUsingtheFluentConfigurationAPI.

ToaddtheCryptographyApplicationBlock1. Opentheconfigurationfile.Formoreinformation,seeConfiguring

EnterpriseLibrary.2. OpentheBlocksmenuandthenclickAddCryptographySettings.3. TheconfigurationtoolautomaticallyaddstheCryptographySettings

section,andtheHashProvidersandSymmetricCryptographyProviderssubsections,withdefaultsettings.

4. ToeditthepropertiesoftheCryptographySettingssection,clickthepropertyexpanderchevron.

Toconfigureahashalgorithmprovider1. ClicktheHashProvidersplussignicon,pointtoAddHash

Providers,andthenclickAddHashAlgorithmProvider.2. Inthetypeselectordialog,selectthehashalgorithmprovidertypeyou

wanttouse.Ifthehashproviderisnotincluded,clickAddfromFileorAddfromGACtolocatetheassemblythatcontainstherequiredtype.

3. (Optional)IntheNamepropertytextbox,changethenameofthehashalgorithmprovider.Thedefaultnameisthetypenameyouselectedinstep2.

4. SettheSaltEnabledpropertybyclickingTrueorFalseinthedrop-downlist.ThedefaultisTrue.

Note:TheCryptographicKeyWizardappearsforkeyedhashalgorithmproviders.Forinformationaboutgeneratingandimportingkeys,seethesectionUsing

theCryptographicKeyWizardlaterinthistopic.

Toconfigureacustomhashprovider1. ClicktheHashProvidersplussignicon,pointtoAddHash

Providers,andthenclickAddCustomHashProvider.

2. Inthetypeselectordialogeithertypethefullpathnameforacustomhashproviderornavigatetoitinthelist.Youcanfiltertheclassesdisplayedbytypinginthetextbox.Toaddacustomproviderfromanotherassembly,clickAddfromFileandnavigatetotheassemblyfile.Toaddaproviderstoredintheglobalassemblycache(GAC),clickAddfromGAC.

3. (Optional)AddcustomAttributesKey/Valuepairsintheeditbox.

4. (Optional)SettheNamepropertybytypingthenameintheeditbox.ThedefaultnameisthenameofthetypeselectedbyusingtheTypeSelectortool.

ToconfigureaDPAPIsymmetriccryptographyprovider1. ClicktheSymmetricCryptographyProvidersplussignicon,pointto

AddSymmetricCryptographyProviders,andthenclickAddDPAPISymmetricCryptoProvider.

2. (Optional)ChangetheNamepropertyoftheDPAPIsymmetriccryptographyprovider.ThedefaultnameisDPAPISymmetricCryptoProvider.

3. SettheProtectionScopeproperty.Inthedrop-downlist,clickCurrentUserorLocalMachine.TheCurrentUservaluemeansthatDPAPIusesaloadeduserprofiletogeneratethekey.Onlythatparticularuseraccountcandecrypttheencrypteddata.TheLocalMachinevaluemeansthatthatanycoderunningonthemachinehasaccesstotheprotectedkey;therefore,itcandecryptanysecretencryptedinLocalMachinemode.Tocounteractthis,yourapplicationcodecanpassanentropyvaluewhenitcallstheEncryptorDecryptmethods.Entropymakesitmoredifficultforoneapplication,runningonthesamecomputer,tocompromiseanotherapplication'sencryptionkey.However,youmustprotecttheentropyvalue.Ifitissimplysavedtoanunprotectedfile,attackerscanaccessthefile,retrievetheentropyvalue,anduseittodecryptanapplication'sdata.TheCryptographyApplicationBlockconfigurationdoesnotincludetheentropyvalue.Thismeansthatyoucannotusetheconfigurationtoolstocreateorsaveanentropyvalue.

Toconfigureasymmetricalgorithmprovider1. ClicktheSymmetricCryptographyProvidersplussignicon,pointto

AddSymmetricCryptographyProviders,andthenclickAddSymmetricAlgorithmProvider.

2. Inthetypeselectordialog,selectthesymmetricalgorithmprovidertypeyouwanttouse.Youcanfiltertheclassesdisplayedbytypinginthetextbox.Toaddacustomproviderfromanotherassembly,clickAddfromFileandnavigatetotheassemblyfile.Toaddaproviderstoredintheglobalassemblycache,clickAddfromGAC.

3. Afterselectingthealgorithmprovider,theCryptographicKeyWizardwillruntoeitherimportorgenerateakey.FormoreinformationonusingtheWizard,seeUsingtheCryptographicKeyWizard.

4. OnthefinalpageoftheWizardclickonFinishtoaddthenewprovider.

Toconfigureacustomsymmetriccryptographyprovider1. ClicktheSymmetricCryptographyProvidersplussignicon,pointto

AddSymmetricCryptographyProviders,andthenclickAddCustomSymmetricCryptoProvider.

2. Inthetypeselectordialogeithertypethefullpathnameforthecustomsymmetriccryptographyproviderornavigatetoit.Youcanfiltertheclassesdisplayedbytypinginthetextbox.Toaddacustomproviderfromanotherassembly,clickAddfromFileandnavigatetotheassemblyfile.Toaddaproviderstoredintheglobalassemblycache,clickAddfromGAC.

3. (Optional)AddcustomAttributesKey/Valuepairsintheeditbox.4. (Optional)IntheNamepropertytextbox,changethenameofthe

customsymmetriccryptographyprovider.ThedefaultnameisthenameofthetypeselectedbyusingtheTypeSelectortool.

Toconfigurethedefaultprovidersfortheblock1. OpentheCryptographySettingspropertiesbyeitherrightclickingon

theCryptographySettingssectionorbyclickingonthepropertyexpanderchevron.

2. (Optional)Inthepropertiespane,settheDefaultHashProviderproperty.ThissetstheinstanceofthehashproviderthattheCryptographyApplicationBlockusesiftheapplicationcodedoesnotspecifyanotherprovider.Inthedrop-downlist,clickthehashprovider.Thedefaultisnone.

3. (Optional)Inthepropertiespane,settheDefaultSymmetricCryptoProviderproperty.ThissetstheinstanceofthesymmetriccryptographyproviderthattheCryptographyApplicationBlockusesiftheapplicationcodedoesnotspecifyanotherprovider.Inthedrop-downlist,clickthesymmetricprovider.Thedefaultisnone.

UsingtheCryptographicKeyWizard




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Entering Configuration Information'%0AEntLib50_c1e33058-145c-47fb-a7cd-158e0b1468c5%0APlease provide details of the error you have located...%0A


SourceSchemafortheCryptographyApplicationBlock

ThistopicliststheXMLelementsandattributesusedtoconfiguretheCryptographyApplicationBlock.YoucanmanuallyedittheXMLdata,buttheEnterpriseLibraryconfigurationtoolsgreatlysimplifythistask.IfyouchoosetomanuallyedittheXML,usetheschemainformationcontainedinthistopic.

Theconfigurationfilehasthefollowingsection-handlerdeclaration.XML

<sectionname="securityCryptographyConfiguration"

type="Microsoft.Practices.EnterpriseLibrary.Security.Cryptography.Configuration.CryptographySettings,

Microsoft.Practices.EnterpriseLibrary.Security.Cryptography"/>

Thesection-handlerdeclarationcontainsthenameoftheconfigurationsettingssectionandthenameofthesection-handlerclassthatprocessesconfigurationdatainthatsection.ThenameoftheconfigurationsettingssectionissecurityCryptographyConfiguration.Thenameofthesection-handlerclassisCryptographySettings.ItisintheMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography.Configurationnamespace.

securityCryptographyConfigurationElement

hashProvidersChildElement

symmetricCryptoProvidersChildElement




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Source Schema for the Cryptography Application Block'%0AEntLib50_e96ffd42-238b-46cd-8b30-719f0d0d6780%0APlease provide details of the error you have located...%0A


MaximizingSecurity

TwoimportantpointsyoushouldconsiderwhenyouusetheCryptographyApplicationBlockarehowyouaregoingtomanagesymmetricencryptionkeysandwhichhashingalgorithmorsymmetricencryptionalgorithmyouaregoingtouse.

ManagingandDistributingKeys

SelectinganEncryptionAlgorithmToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Maximizing Security'%0AEntLib50_41441159-bf5b-468f-b6cc-7b51aaa41bca%0APlease provide details of the error you have located...%0A



TheCryptographyApplicationBlockisdesignedtosupportcommonscenariosforsymmetricencryptionandhashing.Whenyouaddyourapplicationcode,refertothescenariosinKeyScenariosandselecttheonesthatbestsuityoursituation.Usethecodethataccompaniesthescenarioeitherasitisshownhereoradaptitasneeded.

Toprepareyourapplication1. AddareferencetotheCryptographyApplicationBlockassembly.In

VisualStudio®,right-clickyourprojectnodeinSolutionExplorer,andthenclickAddReference.ClickBrowsetolocatetheMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography.dllassembly.Selecttheassembly,andthenclickOK.

2. Followingthesameprocedure,setareferencetothefollowingassemblies:

Microsoft.Practices.EnterpriseLibrary.Common.dllMicrosoft.Practices.Unity.dllMicrosoft.Practices.ServiceLocation.dllMicrosoft.Practices.Unity.Interception.dll

3. (Optional)TouseelementsfromtheCryptographyApplicationBlockwithoutfullyqualifyingtheelementreference,youcanaddthefollowingusingstatement(C#)orImportsstatement(VisualBasic)tothetopofyoursourcecodefile.C#

usingMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography;

VisualBasic

ImportsMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography

4. Next,addtheapplicationcode.

Note:ForMicrosoft®VisualBasic®projects,youcanalsousetheReferencespageoftheProjectDesignertomanagereferencesandimportednamespaces.ToaccesstheReferencespage,selectaprojectnodeinSolutionExplorer,andthenclickPropertiesontheProjectmenu.WhentheProjectDesignerappears,clicktheReferencestab.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Application Code'%0AEntLib50_1c8f6c8b-6e49-43bf-85c3-47cf55970b11%0APlease provide details of the error you have located...%0A


KeyScenarios

Thistopicdescribesthemostcommonsituationsthatdevelopersmustaddresswhenprovidingcryptographyfunctionalityintheirapplications.Eachscenarioexplainsthetask,describesareal-worldsituationwheresuchataskmightoccur,andincludescodethatdemonstrateshowtousetheCryptographyApplicationBlocktocompletethetask.Thescenariosarethefollowing:

EncryptingDataUsingaSymmetricProvider.Thisscenarioillustrateshowyoucanuseasymmetricalgorithmprovidertoencryptasecret.DecryptingDataUsingaSymmetricProvider.Thisscenarioillustrateshowyoucanuseasymmetricalgorithmprovidertodecryptasecretthathasbeenencrypted.ObtainingaHashValue.Thisscenarioillustrateshowyoucangenerateahashvaluefromdata.CheckingWhetheraHashValueMatchesSomeText.Thisscenarioillustrateshowyoucancompareplaintextdatawithahashvaluepreviouslygeneratedfromthedata.Bydoingthis,youcanverifythatthedatahasnotbeenchangedsincethehashwasoriginallygenerated.

Note:Thenon-staticfacadenamedCryptographyManagerreplacesthestaticCryptographerfacadeusedinpreviousversionsofEnterpriseLibrary.However,codethatusestheCryptographerfacadewillcontinuetoworkinthisrelease.ForinformationaboutresolvingEnterpriseLibraryobjectsinyourapplications,seeCreatingandReferencingEnterpriseLibraryObjects.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Key Scenarios'%0AEntLib50_1e96b2bf-8c26-4617-9ec5-766c443b28ec%0APlease provide details of the error you have located...%0A


EncryptingDataUsingaSymmetricProvider

Acommoncryptographytaskistoencryptdatausingasymmetricprovider.Youmaywanttodothiswhenanapplicationhasdatayouwanttokeepsecure.

TypicalGoals

Solution

UsingEncryptSymmetric




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Encrypting Data Using a Symmetric Provider'%0AEntLib50_7984eeb3-96ed-48aa-bb7e-dfa003c5a10d%0APlease provide details of the error you have located...%0A


DecryptingDataUsingaSymmetricProvider

Ifyouencryptdatabyusingasymmetricencryptionprovider,youusuallyhavetodecryptthedatausingthesameprovider.

TypicalGoals

Solution

UsingDecryptSymmetric




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Decrypting Data Using a Symmetric Provider'%0AEntLib50_b42b8250-1500-42ff-b922-49e6437c3e68%0APlease provide details of the error you have located...%0A


ObtainingaHashValue

Anexampleofwhenyoumightwanttoobtainahashvalueiswhenyouhaveapasswordthatyoudonotwanttopassoverthenetwork.

TypicalGoals

Solution

UsingCreateHash




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Obtaining a Hash Value'%0AEntLib50_510b7fe1-40eb-4c75-9c46-e57f67381c5d%0APlease provide details of the error you have located...%0A


CheckingWhetheraHashValueMatchesSomeText

Anexampleofwhenyouwouldcheckwhetherahashmatchessometextiswhenyouhavetoverifythatdatahasnotbeenchangedintransitoveranetwork.Inthiscase,thehashvalueforthedatawouldbestoredattheserver,andwhenthedataarrivesattheserver,itiscomparedagainstthehashvalue.

TypicalGoals

Solution

UsingCompareHash




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Checking Whether a Hash Value Matches Some Text'%0AEntLib50_1c18e9a2-6f51-464e-9a94-e7f6878d1d79%0APlease provide details of the error you have located...%0A


DesignoftheCryptographyApplicationBlock

Thistopicdescribesthedesigngoals,designhighlights,andtheimplementationoftheCryptographyApplicationBlock.

DesignGoals

DesignHighlights

KeyManagementModelToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Cryptography Application Block'%0AEntLib50_31af9345-6f8f-475b-ba2d-e9e88f0ae592%0APlease provide details of the error you have located...%0A


DesigningforSimplifiedCryptographyFunctionality

Cryptographyinapplicationscanbeimplementedinmanyways.Typically,developersmustduplicatecodetoperformcommontasks.Tomeettheneedsoftheirorganization,theymayhavetofamiliarizethemselveswithmanydifferentwaysofimplementingcryptography.TheCryptographyApplicationBlockisdesignedtosimplifyandabstracttheimplementationofcryptographyinapplications.

DesignImplications




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Designing for Simplified Cryptography Functionality'%0AEntLib50_fd12ca97-5d05-4dcd-9947-a49c3f04f307%0APlease provide details of the error you have located...%0A


DesigningforAlgorithmAbstraction

WiththeCryptographyApplicationBlock,developerscanrefertothealgorithmtobeusedbythevariousmethodsbyusinglogicalnames,suchas"hashprovider"or"passwordencryption."

DesignImplications




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Designing for Algorithm Abstraction'%0AEntLib50_de12e414-36a0-4cdd-9890-bb6bdeceeb3f%0APlease provide details of the error you have located...%0A


ExtendingandModifyingtheCryptographyApplicationBlock

Initsoriginalstate,theCryptographyApplicationBlockworkswellfortypicalcryptographyscenarios.However,theremaybetimeswhenyouhavetocustomizesomeoftheblock'sbehaviortobettersuityourapplication'sparticularrequirements.Therearetwowaystocustomizetheblock,extensionandmodification.

ExtendingtheCryptographyApplicationBlock

ModifyingtheCryptographyApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying the Cryptography Application Block'%0AEntLib50_7aec85e0-08ed-41af-8eef-cc7f61be44f8%0APlease provide details of the error you have located...%0A


ExtendingtheCryptographyApplicationBlock

TheCryptographyApplicationBlockisdesignedtobeusedinavarietyofapplicationsandtobeageneral-purposeblock.Extensionpointsletyouadapttheblocktosuittheneedsofanyparticularapplication.Youcanextendthecapabilitiesoftheblockbyaddingcustomcryptographyproviders.Typically,thesecustomprovidersarethird-partycryptographyproviders.Thefollowingtableliststheinterfacesthatyoucanusetoextendtheblock.

CustomProviderorExtension Interface

HashAlgorithmProvider IHashProvider

SymmetricEncryptionAlgorithmProvider ISymmetricCryptoProvider

ToextendtheCryptographyApplicationBlock1. Createanewcustomclassandaddittoyourproject.2. Makesuretheclassimplementstherequiredinterfaces,constructors,

andmethods.3. ConfigurethegenericproviderintheEnterpriseLibraryconfiguration

tools:Specifyyourcustomclassasthetypename.Specifyanycustomconfigurationpropertiesbymodifyingtheattributesoftheobject.

Tocreateacustomhashalgorithmprovider1. Createanewclass,andthenaddittoyourproject.2. (Optional)Touseelementswithoutfullyqualifyingtheelement

reference,youcanaddthefollowingusingstatement(C#)orImportsstatement(VisualBasic)tothetopofyoursourcecodefile.C#


usingMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography.Configuration;

CopyCode

VisualBasic


ImportsMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography.Configuration


3. SpecifythattheclassimplementsIHashProvider.4. AddtheclassattributeConfigurationElementType.Specifythetype

CustomHashProviderDataastheattributeparameter.C#

[ConfigurationElementType(typeof(CustomHashProviderData))]

publicclassMyHashProvider:IHashProvider

VisualBasic

<ConfigurationElementType(GetType(CustomHashProviderData))>_

PublicClassMyHashProvider

ImplementsIHashProvider

5. AddaconstructorthathasaparameteroftypeNameValueCollection.C#

publicMyHashProvider(NameValueCollectionattributes)

{

}

VisualBasic

PublicSubNew(ByValattributesAsNameValueCollection)

EndSub

6. AddtheCreateHashandCompareHashmethodstoyourclass,andthenimplementtherequiredbehavior.C#

publicbyte[]CreateHash(byte[]plaintext)

{

}

publicboolCompareHash(byte[]plaintext,byte[]hashedtext)

{

}

VisualBasic

PublicFunctionCreateHash(ByValplaintextAsByte())AsByte()

EndFunction

PublicFunctionCompareHash(ByValplaintextAsByte(),ByValhashedtextAsByte())AsBoolean

EndFunction

Tocreateacustomsymmetricencryptionalgorithmprovider1. Createanewclass,andthenaddittoyourproject.2. (Optional)Touseelementswithoutfullyqualifyingtheelement

reference,youcanaddthefollowingusingstatement(C#)orImportsstatement(VisualBasic)tothetopofyoursourcecodefile.C#


usingMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography.Configuration;

VisualBasic


ImportsMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography.Configuration


3. SpecifythattheclassimplementsISymmetricCryptoProvider.4. AddtheclassattributeConfigurationElementType.Specifythetype

CustomSymmetricCryptoProviderDataastheattributeparameter.C#

[ConfigurationElementType(typeof(CustomSymmetricCryptoProviderData))]

publicclassMyCustomEncryptionProvider:ISymmetricCryptoProvider

VisualBasic

<ConfigurationElementType(GetType(CustomSymmetricCryptoProviderData))>_

PublicClassMyCustomEncryptionProvider

ImplementsISymmetricCryptoProvider

5. AddaconstructorthathasaparameteroftypeNameValueCollection.C#

publicMyCustomEncryptionProvider(NameValueCollectionattributes)

{

}

VisualBasic

CopyCode

PublicSubNew(ByValattributesAsNameValueCollection)

EndSub

6. AddtheEncryptandDecryptmethodstoyourclass,andthenimplementtherequiredbehavior.C#

publicbyte[]Encrypt(byte[]plaintext)

{

}

publicbyte[]Decrypt(byte[]ciphertext)

{

}

VisualBasic

PublicFunctionEncrypt(ByValplaintextAsByte())AsByte()

EndFunction

PublicFunctionDecrypt(ByValciphertextAsByte())AsByte()

EndFunction





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending the Cryptography Application Block'%0AEntLib50_2adb34c9-fd44-4eb1-961d-1d172a0adb1b%0APlease provide details of the error you have located...%0A


ModifyingtheCryptographyApplicationBlock

TheCryptographyApplicationBlockwasdesignedtobeusedinavarietyofapplicationsandtobeageneral-purposecryptographyapplicationblock.Extensionpointsletyouadapttheblocktosuittherequirementsofanyparticularapplication.However,ifyouwanttoaddnewfeaturestotheblock,youcandosobymodifyingthesourcecode(theblockincludesboththesourcecodeandthebinaries).

Note:Whenmodifyingthesourcecode,youshouldfollowgoodpracticesdescribedinthetopicExtendingandModifyingEnterpriseLibrary.

ModifyingtheKeyManagementCode



http://msdn2.microsoft.com/en-us/library/tswxhw92.aspx

http://msdn2.microsoft.com/en-us/library/y0y718c2(en-US,VS.80).aspx

http://msdn2.microsoft.com/en-us/library/34wz2253(VS.80).aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Modifying the Cryptography Application Block'%0AEntLib50_f31b7417-8c71-45e2-a6e6-b0ae7e4fb2d9%0APlease provide details of the error you have located...%0A



Twoofanadministrator'smaintaskswillbetomakesurethattheinitialdeploymentoftheCryptographyApplicationBlockisplannedandmanagedandtomakesurethatsubsequentupdatesaredeployedwithminimalimpacttoexistingapplicationsthatusetheblock.Fordetails,seeDeployingtheCryptographyApplicationBlock.

Inaddition,administratorsmustdecideiftheywanttousetheinstrumentationexposedbytheblock.Fordetailsofhowtoenableanddisableinstrumentation,seeEnablingInstrumentation.ForinformationontheinstrumentationcontainedwithintheCryptographyApplicationBlock,seethefollowingtopics:

CryptographyApplicationBlockPerformanceCountersCryptographyApplicationBlockEventLogEntries




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deployment and Operations'%0AEntLib50_75506864-1e81-40bd-bde6-755964cb15a0%0APlease provide details of the error you have located...%0A


DeployingtheCryptographyApplicationBlock

TheCryptographyApplicationBlockiscomprisedofmultipleassemblies.EachassemblythatbelongstotheCryptographyApplicationBlockhasafilenamethatbeginswithMicrosoft.Practices.EnterpriseLibrary.Security.Cryptography.Additionally,theblockdependsonthecommonassemblyandontheUnitysubsystem.FordetailsofdeployingandupdatingEnterpriseLibraryandtheblocks,seeDeployingEnterpriseLibrary.

DistributingKeysToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deploying the Cryptography Application Block'%0AEntLib50_7bb0dec0-b753-4ace-aa54-6b4c908145c0%0APlease provide details of the error you have located...%0A


CryptographyApplicationBlockPerformanceCounters

ThefollowingtabledescribestheCryptographyApplicationBlockperformancecounters.

PerformanceCounter Description

HashComparisons/sec Therateatwhichhashcomparisonswereperformed.

HashMismatches/sec Therateatwhichhashcomparisonmismatchesweredetected.

HashOperations/sec Therateatwhichplaintextwashashed.

SymmetricDecryptions/sec

Therateatwhichsymmetricdecryptionswereperformed.

SymmetricEncryptions/sec

Therateatwhichsymmetricencryptionswereperformed.

TotalHashComparisons

Thetotalnumberofhashcomparisonsperformed.

TotalHashMismatches Thetotalnumberofhashcomparisonmismatchesdetected.

TotalHashOperations Thetotalnumberofplaintexthashingoperationsperformed.

TotalSymmetricDecryptions

Thetotalnumberofsymmetricdecryptionsperformed.

TotalSymmetricEncryptions

Thetotalnumberofsymmetricencryptionsperformed.






mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Cryptography Application Block Performance Counters'%0AEntLib50_4470b65a-fd7c-4f11-af2a-5dae571b3b4a%0APlease provide details of the error you have located...%0A


CryptographyApplicationBlockEventLogEntries

ThistopicliststheCryptographyApplicationBlockeventlogentries.Thelisteneristheclassthatraisedtheevent.

CryptographicOperationFailedEvent(SymmetricAlgorithm)

CryptographicOperationFailedEvent(HashAlgorithm)

ConfigurationFailureEventToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Cryptography Application Block Event Log Entries'%0AEntLib50_c1909b84-91a1-4808-8331-1ad4237db7f3%0APlease provide details of the error you have located...%0A


TheDataAccessApplicationBlock

TheEnterpriseLibraryDataAccessApplicationBlocksimplifiesthedevelopmentoftasksthatimplementcommondataaccessfunctionality.Applicationscanusethisapplicationblockinavarietyofsituations,suchasreadingdatafordisplay,passingdatathroughapplicationlayers,andsubmittingchangeddatabacktothedatabasesystem.

TheapplicationblockincludessupportforbothstoredproceduresandinlineSQLstatements.Commonhousekeepingtasks,suchasmanagingconnectionsandcreatingandcachingparameters,areencapsulatedintheapplicationblock'smethods.Inotherwords,theDataAccessApplicationBlockprovidesaccesstothemostoftenusedfeaturesofADO.NETinsimple-to-useclassesandprovidesacorrespondingboostindeveloperproductivity.

ThissectionincludesthefollowingtopicsthatwillhelpyoutounderstandandusetheDataAccessApplicationBlock:

WhatDoestheDataAccessApplicationBlockDo?Thistopicprovidesabriefoverviewthatwillhelpyoutounderstandwhattheblockcando,andexplainssomeoftheconceptsandfeaturesitincorporates.Italsoprovidesasimpleexampleofthewaythatyoucanwritecodetousetheblock.WhenShouldIUsetheDataAccessApplicationBlock?Thistopicwillhelpyoutodecideiftheblockissuitableforyourrequirements.Itexplainsthebenefitsofusingtheblock,andanyalternativetechniquesyoumayconsider.Italsoprovidesdetailsofanylimitationsoftheblockthatmayaffectyourdecisiontouseit.DevelopingApplicationsUsingtheDataAccessApplicationBlock.Thisdescribeshowtoconfiguretheapplicationblock,howtoprepareyourapplicationtousetheDataAccessApplicationBlock,andcontainsdetailsofspecificfeaturesoftheapplicationblock,suchashowyoucreateadatabase,workwithtransactions,andhandleparametersandexceptions.KeyScenarios.Thissectiondemonstrateshowtousetheapplicationblocktoperformthemosttypicaldataaccessoperations.DesignoftheDataAccessApplicationBlock.Thissectiondescribesthe

decisionsthatwentintodesigningtheapplicationblockandtherationalebehindthosedecisions.ExtendingandModifyingtheDataAccessApplicationBlock.Thissectiondescribeshowtoextendtheapplicationblockbyaddingyourowndatabaseproviderandgivessuggestionsformodifyingthesourcecode.DeploymentandOperations.Thissectiondescribeshowtodeployandupdatetheapplicationblockassemblies.ItalsocontainsinformationaboutconfigurationandMicrosoft®SQLServer®security.

MoreInformationFormoreinformation,seethefollowingresources:

MicrosoftApplicationArchitectureGuide,2ndEdition-Chapter8:DataLayerGuidelines.NETDataAccessArchitectureGuideINFO:MicrosoftGuideforDesigningDataTierComponentsandPassingDataThroughTiersImprovingWebApplicationSecurity:ThreatsandCountermeasuresImproving.NETApplicationPerformanceandScalability





http://support.microsoft.com/kb/829025




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Data Access Application Block'%0AEntLib50_68577648-b6f9-478f-ad6a-953836e97c53%0APlease provide details of the error you have located...%0A


WhatDoestheDataAccessApplicationBlockDo?

TheDataAccessApplicationBlockincludesasmallnumberofmethodsthatsimplifythemostcommontechniquesforaccessingadatabase.Eachmethodencapsulatesthelogicrequiredtoretrievethedataandmanagetheconnectiontothedatabase.Themethodsexposedbytheblockallowyoutoexecutequeries,returndatainarangeofdifferentformats,populateaDataSet,updatethedatabasefromaDataSet,performdataaccessasynchronously(againstSQLServerdatabases),andreturndataasobjectsinasuitableformatforusewithclient-sidequerytechnologiessuchasLINQ.

ADO.NETprovidesclassessuchastheDbCommandclassandtheDbConnectionclass;theseclasseshelptoabstractthedataproviderfromanyparticulardatabaseimplementation.TheDataAccessApplicationBlocktakesadvantageoftheseclassesandprovidesamodelthatfurthersupportsencapsulationofspecificfeaturesofeachdatabasetype,suchasparameterdiscoveryandtypeconversion.Asaresult,applicationscanoftenbeportedfromonedatabasetypetoanotherwithoutmodifyingtheclientcode.TheDataAccessApplicationBlockincludesanabstractbaseclassthatdefinesacommoninterfaceandprovidesmuchoftheimplementationrequiredbythedataaccessmethodsavailableinADO.NET.

TheapplicationblockalsoincludesclassesdesignedtoworkwithMicrosoftSQLServer,MicrosoftSQLServerCE,andOracle.Theseclassesperformoperationsthatarespecifictothedatabasetype.Thecodeforapplicationswrittenforonetypeofdatabase,suchasSQLServer,looksmuchthesameasthecodeforapplicationswrittenforanothertypeofdatabasesuchasOracle.

AnotherfeatureoftheDataAccessApplicationBlockisthatapplicationcodecanrefertoparticulardatabasesbyanADO.NETconnectionstringname,suchas"Customer"or"Inventory."TheapplicationcodecanspecifyanamedinstanceofadatabasewhencreatingtheDatabaseimplementationitusesasafacadeforthemajorityofthemethods.Eachnameddatabasehasitsconnectioninformationstoredinaconfigurationfile.Bychangingthesettingsintheconfigurationfile,developerscanusetheirapplicationswithdifferentdatabasetypeswithoutrecompilingtheircode.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Does the Data Access Application Block Do?'%0AEntLib50_1926dac4-788f-4222-b2ae-877ec6f307bc%0APlease provide details of the error you have located...%0A


WhenShouldIUsetheDataAccessApplicationBlock?

YoushouldconsiderusingtheDataAccessApplicationBlockifyourapplicationusesstandarddataaccesstechniques.Theblockisparticularlysuitedtoquerying,retrieving,andupdatingdatathroughimplementationsbasedontheExecuteReader,ExecuteXmlReader,andExecuteNonQuerymethodscommonlyusedinADO.NET—includingtheasynchronousversionsofthesemethods.ItalsoprovidesmethodstopopulateDataSetinstances,andflushthechangesbacktothedatabase.

Youshouldalsoconsiderusingtheblockifyouwanttoworkwithdatausingclient-sidequeryingmechanismssuchasLanguageIntegratedQuery(LINQ).Itcontainssupportfortheseprogrammingtechniquesbyexposingmethodsthatreturndataassequencesofobjects.

AthirdreasonforusingtheDataAccessApplicationBlockisitscapabilitytoabstractthedatabasetype.Thismakesiteasiertochangeyourapplicationtouseadifferenttypeofdatabaseifrequired,althoughsomeofthemoreadvanceddataaccessmethodsdorelyonthespecificcapabilitiesoftheunderlyingADO.NETDataProvider.

ScenariosfortheDataAccessApplicationBlock

BenefitsoftheDataAccessApplicationBlock

LimitationsoftheDataAccessApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://msdn.microsoft.com/en-us/library/cc656912(VS.100).aspx

http://msdn.microsoft.com/en-us/library/bb398202(VS.100).aspx



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'When Should I Use the Data Access Application Block?'%0AEntLib50_dbe9caf2-5dda-466d-beec-0e0ab1a0031b%0APlease provide details of the error you have located...%0A


DevelopingApplicationsUsingtheDataAccessApplicationBlock

ThissectiondescribeshowyoucanusetheDataAccessApplicationBlocktodevelopapplications.Itfirstexplainshowtoconfiguretheapplicationblockandincorporateitintoyourapplications.Next,itexplainshowtousetheapplicationblockforspecificscenarios,suchasretrievingasingleitemorusingaDataSetobjecttoretrievemultiplerows.Lastly,itprovidesmoreinformationabouttopicssuchasconnectionmanagement,parameterhandling,andhandlingexceptions.

Thissectionassumesthatyouareusingtheapplicationblockinitsoriginalstate,withoutextendingit.(Tolearnhowtoaddfunctionality,seeExtendingandModifyingtheDataAccessApplicationBlock.)Thissectionincludesthefollowingtopics:

EnteringConfigurationInformationAddingApplicationCodeCreatingaDatabaseObjectCreatingaDbCommandObjectManagingConnectionsUsingtheTransactionScopeClassUsingtheAsynchronousDataAccessMethodsReturningDataasObjectsforClientSideQueryingCreatingPortableDatabaseApplicationsHandlingExceptionsHandlingParameters


Note:TheDataAccessBlockcannotbeusedinapplicationsthattargetthe.NETFramework4.0ClientProfile.Itcanonlybeusedinapplicationsthattargetthefull.NETFramework4.0profile.Forinformationaboutprofilesinthe

.NETFramework4.0,see.NETFrameworkClientProfileonMSDN.Forinformationaboutchangingthetargetedprofile,seeHowto:TargetaSpecific.NETFrameworkVersionorProfileonMSDN.



http://msdn.microsoft.com/en-us/library/cc656912(VS.100).aspx

http://msdn.microsoft.com/en-us/library/bb398202(VS.100).aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Developing Applications Using the Data Access Application Block'%0AEntLib50_805fe253-7a47-4799-9802-0989ebf3af5c%0APlease provide details of the error you have located...%0A



ThefollowingproceduresdescribehowtoconfiguretheDataAccessApplicationBlock.PropertiesassociatedwiththenodesappearintherightpaneoftheConfigurationConsoleorthePropertieswindowoftheVisualStudio®ConfigurationEditor.FordetailsoftheschemafortheDataAccessApplicationBlockconfiguration,seeSourceSchemafortheDataAccessApplicationBlock.Youcanalsoconfiguretheblockincodebyusinganalternateconfigurationsource.Formoreinformation,seeAdvancedConfigurationScenariosandUsingtheFluentConfigurationAPI.

ToaddtheDataAccessApplicationBlock1. Opentheconfigurationfile.Formoreinformation,seeConfiguring

EnterpriseLibrary.2. OpentheBlocksmenuandthenclickAddDataSettings.3. TheconfigurationtoolautomaticallyaddstheDatabaseSettings

sectionwithdefaultsettings.ClickthepropertiesexpanderchevronintheDatabaseSettingssectiontoviewthesettingsforthissection.

Thenextprocedureexplainshowtoconfigureaninstanceofthedefaultdatabasethatisaddedautomaticallytotheconfiguration.ThisinstanceisusediftheapplicationresolvesaDatabasewithnoinstancename.

Toconfigurethedefaultdatabase1. IntheDatabaseInstancespane,clicktheexpanderarrowforthe

ConnectionStringsection.

2. (Optional)SettheNamepropertybytypinganewname.ThedefaultnameisConnectionString.

3. UsetheDatabaseProviderpropertytochangetheprovidernameas

required.Enterthenameoftheproviderorselectitfromthedrop-downlist.ThedefaultprovidernameisSystem.Data.SqlClient.Youcanchooseadifferentproviderifyouwish,suchasSystem.Data.OleDb.TheDatabaseProviderpropertymustbeaprovidernamespecifiedinaDBProviderFactoryclass.

4. Clicktheellipses(...)buttonintheConnectionStringpropertytoshowtheconnectionstringinapop-upwindow.Edititasrequired.

Thenextprocedureexplainshowtocreateadditionaldatabaseinstancesforotherdatabases.

Toconfigureadditionaldatabaseinstances1. ClicktheplussigniconintheDatabaseInstancespaneandthenclick

AddDatabasetoaddanewconnectionstringsection.

2. (Optional)SettheNamepropertybytypinganewname.Thisisthenameyouwillusetorefertothedatabase.

3. IntheDatabaseProviderpropertysection,enterthenameofthedatabaseproviderorselectitfromthedrop-downlist.TheDatabaseProviderpropertymustbeaprovidernamespecifiedinaDbProviderFactoryclass.IfyouareusingtheVisualStudiointegratedconfigurationeditorandyoudonotseetheprovidertypeyourequireinthelist,youmustaddareferencetotheassemblycontainingthe

providertoyourproject.4. Clicktheellipses(...)buttonintheConnectionStringpropertyto

showtheconnectionstringinapop-upwindow.Typetheconnectionstringthatthisdatabasewilluse.Forexample,thefollowingconnectionstringspecifiesthedatabasenamedCorpData1ontheSQLServerinstancenamedDBSERVER1usingintegratedWindows®security:

Server=DBSERVER1;InitialCatalog=CorpData1;IntegratedSecurity=SSPI

ThenextproceduredescribeshowtochangewhichofthecurrentlyconfigureddatabasesisthedefaultthatwillbeusediftheapplicationresolvesaDatabasewithnoinstancename.

Tochangethedefaultdatabase1. ClickthepropertiesexpanderchevronintheDatabaseSettingssection

toviewthesettingsforthissectionifitisnotalreadyopen.2. Selectthedatabasethatyouwanttouseasthedefaultinthedrop-down

listfortheDefaultDatabaseInstanceproperty.

ThenextproceduredescribeshowtoconfigureaSQLServerCEdatabase.Thesestepsareappropriateifyourapplicationalwaysusesasinglefilethatyounameduringconfiguration.FormoreinformationaboutSQLServerCE,seeCreatingaDatabaseObject.

ToconfigureSQLServerCE1. ClicktheplussigniconintheCustomDatabasespaneandthenclick

AddCustomDatabaseProvider.2. SettheNamepropertyofthecustomdatabasebytypinganewname.

ThisnameisusedtolinktheSQLServerCEdatabaseprovidertotheconnectionstringyouwilldefineforit.

3. IntheTypeproperty,clicktheellipses(...)button,fullyexpandtheMicrosoft.Practices.EnterpriseLibrary.Data.SqlCenode,andselectSqlCeDatabase.ThenclickOK.

4. ClicktheplussigniconintheDatabaseInstancespaneandthenclickAddDatabaseConnectionString.Thisaddsanewconnectionstringtotheconfiguration,whichyouwillusetospecifytheconnectionstring

CopyCode

fortheSQLServerCEdatabase.Alternatively,youcanconfigurethedefaultConnectionStringitemthattheconfigurationtooladdsifyoudonotrequireanyotherconnectionstringsinyourconfiguration.

5. (Optional)SettheNamepropertyoftheconnectionstringitembytypinganewname.Thisisthenameyouwillusetorefertothedatabaseinyourcode.

6. Clicktheellipses(...)buttonintheConnectionStringpropertytoshowtheconnectionstringinapop-upwindow.EntertheappropriatevaluefortheConnectionStringproperty;forexample:

DataSource='C:\MyApp\MyDatabase.sdf'

Note:TheSQLCEdatabaseiscreatedbytheEnterpriseLibrarySQLDatabaseprovider,whichdoesnotenforcepasswordprotectionorencryptiononthedatabaseduringcreation.Toensuresecurityofyorudata,youshouldconsidersettingtheconnectionstringtoprotectthefileandcreateitwiththecorrectpermissions,andencryptthefile.FormoreinformationseeSqlCEConnectionConnectionStringPropertyonMSDN.

7. Thefollowingexampleenablesencryptiononthedatabase:

"DataSource=MyData.sdf;EncryptDatabase=True;Password=myPassword;FileMode=sharedread;PersistSecurityInfo=False;"

8. SettheDatabaseProviderpropertyofyourSQLServerCEconnectionstringitemtothenameyouenteredforthecustomdatabaseproviderinstep2.ThefollowingscreenshotshowsdetailsoftheconfigurationforaSQLServerCEdatabaseintheconfigurationtools.

http://msdn.microsoft.com/en-us/library/system.data.sqlserverce.sqlceconnection.connectionstring(VS.80).aspx

9. ForinformationonusingSQLServerCE,seethesection"UsingSQLServerCE"inthetopicCreatingaDatabaseObject.

ThenextproceduredescribeshowtoaddOraclepackages.AnOraclepackageservesasawaytogroupstoredproceduresintocommongroups,typicallybasedontheirfunctionality.WhenanapplicationcallsanOraclestoredprocedurelocatedinapackage,thecodemustprefixthestoredprocedurenamewiththepackagename.Forexample,tocallaprocedurenamedGetEmployeeNamethatisinapackagenamedEmployee_pkg,youwouldcallEmployee_pkg.GetEmployeeName.

IncorporatingthiscodeintotheapplicationmakesitlessportablebecausethissyntaxisspecifictoOracle.Instead,theDataAccessApplicationBlockcanprefixthestoredprocedurewiththepackagename.Thismeansyourclientcodedoesnotneedtospecifythepackagenametocallastoredprocedure.Todothis,theapplicationblockusesinformationintheconfigurationfile.TheOraclePackagenodestoresaname/prefixpair.Thenameisthenameofthe

package.Theprefixisastringthatisassociatedwiththepackage.Allstoredproceduresthatstartwiththatprefixareassumedtobeintheassociatedpackage.

Whentheapplicationcallsastoredprocedure,theDataAccessApplicationBlockcheckstoseeifitbeginswithanyoftheprefixesintheconfigurationfile.Ifitdoes,theapplicationblockprefixesthestoredprocedurewiththeassociatedpackagename.(Thefirstmatchitfindsistheonetheapplicationblockuses.)Ifyouspecifyanasterisk("*")astheprefix,theassociatedpackageisusedforallstoredprocedurecalls.

ToconfigureanOraclepackage1. ClicktheplussigniconintheOracleConnectionspane,andclick

AddOracleConnection.2. AnOraclePackagesforOracleConnectionsectionisaddedtothe

OracleConnectionspaneanditspropertiesaredisplayed.3. (Optional)SettheNamepropertybytypinganewname.4. ClicktheplussigniconinthePackagesrowtoaddanewpackage.

5. ChangetheNamepropertybyenteringthenameoftheOraclepackage.ThedefaultnameisPackage.

6. EnteravalueforthePrefixproperty.

Note:TheOracleClientdataproviderisdeprecatedinversion4.0ofthe.NETFramework,althoughitisstillsupportedbytheEnterpriseLibrary5.0.Forfuturedevelopment,considerchoosingadifferentOracledriver,suchasthatavailablefromtheEnterpriseLibraryContribsite.

Thenextproceduredescribeshowtoaddcustomprovidermappingsby


associatingaproviderwiththefullyqualifiednameofadatabase.

Toconfigureacustomprovider1. ClicktheplussigniconintheCustomDatabasespane,andthenclick

onAddCustomDatabaseProvider.2. (Optional)SettheNamepropertybytypinganewnameorselectit

fromthedrop-downlist.ThedefaultprovidernameisCustomDatabaseProvider.

3. IntheTypepropertytextbox,clicktheellipsisbutton(…)andusethetypeselectortoselectthefullyqualifiednameoftheEnterpriseLibrarydatabasetype.Iftheproviderisregisteredintheglobalassemblycache(GAC),clicktheAddfromGACbuttontolocateit.IfyouareusingtheVisualStudiointegratedconfigurationeditorandyoudonotseetheprovidertypeyourequireinthelist,youmustaddareferencetotheassemblycontainingtheprovidertoyourproject.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Entering Configuration Information'%0AEntLib50_2487249b-8d44-4ce2-9a7f-ada5d8b0a56b%0APlease provide details of the error you have located...%0A


SourceSchemafortheDataAccessApplicationBlock

ThistopicliststheXMLelementsandattributesusedtoconfiguretheDataAccessApplicationBlock.YoucanmanuallyedittheXMLdata,buttheEnterpriseLibraryconfigurationtoolsgreatlysimplifythistask.IfyouchoosetomanuallyedittheXML,usetheschemainformationcontainedinthistopic.


<configSections>

<sectionname="dataConfiguration"

type="Microsoft.Practices.EnterpriseLibrary.Data.Configuration.DatabaseSettings,

Microsoft.Practices.EnterpriseLibrary.Data"/>

<sectionname="oracleConnectionSettings"

type="Microsoft.Practices.EnterpriseLibrary.Data.Oracle.Configuration.OracleConnectionSettings,

Microsoft.Practices.EnterpriseLibrary.Data"/>

</configSections>

Thesection-handlerdeclarationcontainsthenameoftheconfigurationsettingssectionsandthenamesofthesection-handlerclassesthatprocessconfigurationdatainthatsection.ThenameofthefirstconfigurationsettingssectionisdataConfiguration.Thenameofthesection-handlerclassisDatabaseSettings(intheMicrosoft.Practices.EnterpriseLibrary.Data.Configurationnamespace).

ThenameofthesecondconfigurationsettingssectionisoracleConnectionSettings.Thenameofthesection-handlerclassisOracleConnectionSettings(intheMicrosoft.Practices.EnterpriseLibrary.Data.Oracle.Configurationnamespace).

connectionStringsElement

dataConfigurationElement

providerMappingsChildElement

oracleConnectionSettings

packagesChildElement




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Source Schema for the Data Access Application Block'%0AEntLib50_c970d38b-d1b3-4813-bb16-36f9d4868fce%0APlease provide details of the error you have located...%0A

CopyCode

CopyCode



TheDataAccessApplicationBlockisdesignedtosupportthemostcommonscenariosforaccessingadatabase.Whenyouaddyourapplicationcode,refertothescenariosintheKeyScenariossectionandselecttheonesthatbestmatchyoursituation.Usethecodethataccompaniesthescenarioas-isoradaptitasnecessary.

First,youmustprepareyourapplicationtousetheDataAccessApplicationBlock.Afteryoudothat,youcancreatetheDatabaseobjectandcalltheappropriatemethodoverloads.

Toprepareyourapplication1. AddareferencetotheDataAccessApplicationBlockassembly.In

VisualStudio,right-clickyourprojectnodeinSolutionExplorer,andthenclickAddReference.ClicktheBrowsetab,andthennavigatetothelocationoftheMicrosoft.Practices.EnterpriseLibrary.Data.dllassembly.Selecttheassembly,andthenclickOKtoaddthereference.

2. Followingthesameprocedure,addreferencestothefollowingassemblies:

Microsoft.Practices.EnterpriseLibrary.Common.dllMicrosoft.Practices.Unity.dllMicrosoft.Practices.ServiceLocation.dllMicrosoft.Practices.Unity.Interception.dll.

3. (Optional)TouseelementsfromDataAccessApplicationBlockwithoutfullyqualifyingtheelementreference,youcanaddthefollowingusingstatement(C#)orImportsstatement(VisualBasic®)tothetopofyoursourcecodefile.C#

usingMicrosoft.Practices.EnterpriseLibrary.Data;

usingSystem.Data;

VisualBasic

ImportsMicrosoft.Practices.EnterpriseLibrary.Data

ImportsSystem.Data

Note:ForVisualBasicprojects,youcanusetheReferencespageoftheProjectDesignertomanagereferencesandimportednamespaces.ToaccesstheReferencespage,selectaprojectnodeinSolutionExplorer.OntheProjectmenu,clickProperties.WhentheProjectDesignerappears,clicktheReferencestab.

ForinformationonhowtocreateaDatabaseobjectandadviceonusingtheDatabasetypes,seeCreatingaDatabaseObject.

Forinformationaboutthekeyscenariosforusingtheblock,seeKeyScenarios.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Application Code'%0AEntLib50_b4418970-becb-44b5-9c74-57bacd4f6d8b%0APlease provide details of the error you have located...%0A


CreatingaDatabaseObject

AlldataaccessmethodsareexecutedagainstaDatabaseobject.YoucanusetheEnterpriseLibrarycontainertocreateaDatabaseobject.ThespecifictypeofDatabaseobjectitreturnsisdeterminedbytheapplicationconfigurationinformation.Bychangingthedefaultconfiguration,theunmodifiedapplicationcanberunagainstdifferentdatabases.Theconnectionstringinformationforeachdatabaseyoudefineisstoredinthe<connectionStrings>sectionintheapplicationconfigurationfile.

Thistopicincludesthefollowingsectionsthatdescribehowtocreateinstancesofdifferenttypesofdatabases,andsomethingsyoumustconsiderwhenworkingwithspecifictypesofdatabases:

CreatingaDefaultDatabaseInstanceCreatingaNamedDatabaseInstanceCreatingaSpecificDatabaseTypeCreatingaDatabaseInstanceDirectlyCreatingaGenericDatabaseInstanceWritingCodetoUsetheDatabaseClassesUsingSQLServerCEUsingOraclewiththeTransactionScopeClassUsingtheOracleDataReaderWrapperClass

CreatingaDefaultDatabaseInstance

CreatingaNamedDatabaseInstance

CreatingaSpecificDatabaseType

CreatingaDatabaseInstanceDirectly

CreatingaGenericDatabaseInstance

WritingCodetoUsetheDatabaseClasses

UsingSQLServerCE

http://www.microsoft.com/sqlserver/2008/en/us/compact.aspx

http://msdn2.microsoft.com/en-us/library/system.data.sqlserverce.aspx

UsingOraclewiththeTransactionScopeClass


http://www.oracle.com/technology/software/tech/windows/ora_mts/htdocs/utilsoft.html

UsingtheOracleDataReaderWrapperClassToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating a Database Object'%0AEntLib50_856ba3aa-8c49-449f-8f2d-153d0210d5e4%0APlease provide details of the error you have located...%0A


CreatingaDbCommandObject

TheDataAccessApplicationBlockprovidesaconsistentwaytoretrieveADO.NETDbCommandobjects.ThedataaccessmethodsoftheapplicationblockincludeoverloadsthatacceptaDbCommandobject.IfyouusetheoverloadswithDbCommandobjects,youhavemorecontrolwhenyoucallstoredprocedures.Forexample,ifyouuseaDbCommandobject,youcanhaveastoredprocedurethatreturnsseveralresultsintheoutputparameters.Inaddition,aDbCommandobjectallowsyoutospecifythestoredprocedure'stimeoutvalue.

ThemethodsthatcreateDbCommandobjectsareseparatedintotwotypes:Methodsthatrepresentstoredprocedurecalls(forexample,GetCustomers)MethodsthatrepresentSQLtextcommands(forexample,SelectCustomerID,FullnameFromCustomers)

ThemethodyoucalltoretrieveaDbCommandobjectisdeterminedbywhetheryouwanttoexecuteinlineSQLorcallastoredprocedure.ThemethodthatcreatesaDbCommandobjectforastoredprocedurealsoprovidesparametercaching.Formoreinformationaboutparametercaching,seeHandlingParameters.

AllDbCommandobjectsarecreatedusingmethodsontheDatabaseclass.Thesemethodsarethefollowing:

GetStoredProcCommand.Thismethodisforstoredprocedurescommands.GetSqlStringCommand.ThismethodisforSQLtextcommands.

BothmethodsreturnaDbCommandobject.

Note:SQLServerCEdoesnotsupportstoredprocedures.Instead,useinlineSQLstatements.Formoreinformation,seethesection"UsingSQLServerCE"inCreatingaDatabaseObject.

DbCommandObjectsforSQLStatements

DbCommandObjectsforStoredProceduresToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating a DbCommand Object'%0AEntLib50_e34b065d-c6ff-482b-a8b3-36d060bbf2b8%0APlease provide details of the error you have located...%0A

CopyCode


ManagingConnections

Databaseconnectionsarealimitedresource,andpropermanagementofthemisessentialforscalableapplications.Itisgoodpracticetokeepconnectionsopenonlyaslongastheyareneededandtoclosethemassoonaspractical.Bydesign,mostoftheDatabaseclassmethodshandletheopeningandclosingofconnectionstothedatabaseoneachcall.Therefore,theapplicationcodedoesnotneedtoincludecodeformanagingconnections.(Bydefault,andforperformancereasons,ADO.NETreturnsconnectionstotheconnectionpoolwithoutclosingthem.Therefore,youdonotneedtocacheyourDatabaseobjects.)

Forexample,theExecuteDataSetmethodreturnsaDataSetobjectthatcontainsallthedata.Thisgivesyouyourownlocalcopy.ThecalltoExecuteDataSetopensaconnection,populatesaDataSet,andclosestheconnectionbeforereturningtheresult.

ThefollowingcodedemonstratestheuseoftheExecuteDataSetmethod.ItassumesthatyouhaveresolvedtheDatabaseclassyourequireandstoredareferenceinthevariablenameddb.

Formoreinformationoninstantiatingobjects,seeCreatingandReferencingEnterpriseLibraryObjects.C#

stringsql="SelectProductID,ProductNameFromProducts";

DbCommandcmd=db.GetSqlStringCommand(sql);

//Noneedtoopentheconnection;justmakethecall.

DataSetcustomerDataSet=db.ExecuteDataSet(cmd);

VisualBasic

DimsqlAsString="SelectProductID,ProductNameFromProducts"

DimcmdAsDbCommand=db.GetSqlStringCommand(sql)

'Noneedtoopentheconnection;justmakethecall.

DimcustomerDataSetAsDataSet=db.ExecuteDataSet(cmd)

However,thereareothercaseswhereitisunclearwhentoclosetheconnection.AnexampleistheExecuteReadermethod.ThismethodreturnsanobjectthatimplementstheIDataReaderinterface.TheDatabasebaseclasshasadefaultimplementationthatreturnsaDbDataReaderobject.DbDataReaderobjectsaredesignedtoreadspecificportionsofthedataasneeded,whichrequiresanopenconnection.Inotherwords,itisunknownwhentheapplicationnolongerneedstheDbDataReader.

IftheDataAccessApplicationBlockmethodsclosetheconnectionbeforereturningtheDbDataReader,theDbDataReaderbecomesuselesstotheclientcode.Instead,theDbDataReadermethodsindicatetotheunderlyingADO.NETcalltoautomaticallyclosetheconnectionwhentheDbDataReaderisdisposed.

Note:IfyoufailtoclosetheDbDataReader,youcancauserandomandhard-to-finderrorsinyourcode—particularlywhenyouareoperatingunderanimplicittransactioncreatedwithinaTransactionScopecontext.YoushouldalwaysensurethatyourapplicationclosestheDbDataReaderinatimelyfashion,eitherbyexplicitlyclosingthereaderusingtheDbDataReader.ClosemethodorbyforcingthedisposaloftheDbDataReader,whichresultsintheClosemethodbeingcalled.

ThefollowingcodedemonstratesacalltotheExecuteReadermethod.Theusingstatement(UsinginVisualBasic)ensuresthattheDbDataReaderobjectisdisposed,whichclosestheDbDataReaderobject.ItassumesthatyouhaveresolvedtheDatabaseclassyourequireandstoredareferenceinthevariablenameddb.

Formoreinformationoninstantiatingobjects,seeCreatingandReferencingEnterpriseLibraryObjects.C#

DbCommandcmd=db.GetSqlStringCommand("SelectName,AddressFromCustomers");

using(IDataReaderreader=db.ExecuteReader(cmd))

{

//Processresults

}

VisualBasic

DimcmdAsDbCommand=db.GetSqlStringCommand("SelectName,AddressFromCustomers")

UsingreaderAsIDataReader=db.ExecuteReader(cmd)

'Processresults

EndUsing




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Managing Connections'%0AEntLib50_ab8937b2-cca0-4388-a4bf-2c94f3eeb646%0APlease provide details of the error you have located...%0A


UsingtheTransactionScopeClass

SomeoftheDatabaseclassmethodstakeadvantageofthe.NETFrameworkTransactionScopeclass.Thisclassautomaticallyenlistsdatabasecallsintoanambienttransaction.Thisisusefulforenlistingbusinessobjectsinatransactionwithoutpassingatransactiontothosebusinessobjects.HereisthebasicmodelforusingtheTransactionScopeclass.ItassumesthatyouhaveresolvedtheDatabaseclassyourequireandstoredareferenceinthevariablenameddb.

FormoreinformationoninstantiatingobjectsseeCreatingandReferencingEnterpriseLibraryObjects.C#

using(TransactionScopescope=newTransactionScope(TransactionScopeOption.RequiresNew))

{

intdRows=db.ExecuteNonQuery(CommandType.Text,insertString);

dRows=db.ExecuteNonQuery(CommandType.Text,insertString2);

}

VisualBasic

UsingscopeAsNewTransactionScope(TransactionScopeOption.RequiresNew)

DimdRowsAsInteger=db.ExecuteNonQuery(CommandType.Text,insertString)

dRows=db.ExecuteNonQuery(CommandType.Text,insertString2)

EndUsing

ThetwoExecuteNonQuerymethodsinserttherowswithinthetransactionthatyoudefinewhenyoucreateanewTransactionScopeinstance.

TheTransactionScopeclasscreatesalocal,lightweighttransaction.Itassumesthatyouwilluseasingleconnectionforallofthedatabasecallsthatoccurwithinthetransaction.Thismeansthat,insteadofpassingtheDbTransactioninstance,yousimplypasstheconnection,andthe.NETFrameworkautomaticallysetsthetransactionforeachcommandthatyouexecute.

EnterpriseLibrary,ontheotherhand,normallyopensandclosesaconnection

foreachrequest.ThisapproachisincompatiblewiththewaytheTransactionScopeclassworks.Iftherearemultipleconnections,theTransactionScopeclassconsidersthetransactiontobeadistributedtransaction.Distributedtransactionshaveasignificantperformanceandresourceoverheadcomparedwithalocaltransaction.

Toavoidthis,theDatabaseclassmethods,suchasExecuteDataSet,recognizewhenaTransactionScopeinstanceisactiveandtheyenlistdatabasecallsinthistransaction.IfatransactioniscurrentlyactiveasaresultofusingaTransactionScopeinstance,theDatabaseclassmethodsuseasingleconnection.

Inparticular,theGetOpenConnectionmethodreplacestheOpenConnectionmethodwithintheDatabasemethods.TheGetOpenConnectionmethodreturnsaconnectioninsideawrapper.Themethoddisposesthewrapperifthereisnotransactioninprogress.However,whenatransactionisinprogress,themethodkeepstheconnectionopen.

Note:Multiplethreadssharingthesametransactioninatransactionscopewillcausethefollowingexception:"Transactioncontextinusebyanothersession."




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the TransactionScope Class'%0AEntLib50_3d30d0c9-c89e-4619-a6ea-e1be36de47e7%0APlease provide details of the error you have located...%0A


UsingtheAsynchronousDataAccessMethods

Oneofthemostcommonfactorsthatcanaffectperformanceinapplicationsisaccessingadatabase,andmostsystemdesignsaimtominimizedatabaseroundtrips.Simplycallingacrossanetworktoadatabasecancausesignificantdelays,andtheadditionaldelaywhilethedatabaseprocessesaquerycanbeparticularlytroublesomeininteractiveapplicationswherethedelaycancausetheUItobecomeunresponsive.Toresolvethis,youmayconsiderusingasynchronousmethodstoaccessyourdatabase.

TheDataAccessApplicationBlockcontainsversionsoffourofthedataaccessmethodsthatyoucanexecuteasynchronously.ThesemethodsrelyonthefeaturesoftheunderlyingADO.NETdataprovider,andarethereforeavailableonlyfortheSqlDatabaseimplementationoftheDatabaseclassinthisrelease.TheDatabaseclassexposesamethodnamedSupportsAsyncthateachdatabase-specificclass(suchasSqlDatabase,OracleDatabase,andSqlCeDatabase)implementstoreturntrueorfalse.Thethreepairsofasynchronousmethodsavailablearethefollowing:

BeginExecuteReaderandEndExecuteReader.ThesemethodsareusedtoobtainaDataReaderpopulatedwithdatafromthedatabase.BeginExecuteScalarandEndExecuteScalar.Thesemethodsareusedtoobtainasinglevaluefromthedatabase.BeginExecuteNonQueryandEndExecuteNonQuery.Thesemethodsareusedtoexecuteaquerythatdoesnotreturndata,butreturnsonlyacountofthenumberofrowsaffected.

Inaddition,whenusingSqlDatabasedirectly,anadditionalpairofasynchronousmethodsisavailable:

BeginExecuteXmlReaderandEndExecuteXmlReader.ThesemethodsareusedtoobtainanXmlReaderpopulatedwithdatafromthedatabase.

TheBeginandEndversionsofthemethodsoperateinthesamewayasthoseavailablewhenyoucodedirectlyagainsttheADO.NETprovider.WhenusingtheDataAccessApplicationBlock,youpasstothemethodsthesameparametersasforthenon-asynchronousversions,suchasaDbCommandand(optionally)atransactionreference.ThemethodsreturnaninstanceoftheIAsyncResultinterface,whichyouthenuseastheparameterinacalltothe

Endversionofthemethodtoobtaintheresult.Yourcodewaitsuntilthemethodcompletes.However,youcanuseanarrayofthestandardWindowsWaitHandleclasstostartmultipledataaccessoperations,andthecodewillreturnwhentheyallcompleteortimeout.

Ifyouwanttoexecutecodeinyourapplicationwhilethedataaccesscallisexecuting,youcanusealambdaexpressionoraseparatecallbackthatisexecutedwhendataaccessiscomplete.Ifyouuseaseparatecallback,youpassareferencetoyourcallbackmethodtotheBeginmethod,andoptionallyanobjectcontainingstateinformationthatyouwanttomakeavailableinthecallbackmethod.AcommonuseofthisobjectistopassareferencetotheDatabaseobjectsothatyoucancalltheappropriateEndmethodinsidethecallbackhandler.Ifyouusealambdaexpression,itwillhaveaccesstotheobjects(suchastheDatabaseinstance)thatyouuseinthedataaccesscode.

AsthemethodsforperformingasynchronousexecutionmatchthoseavailablefortheADO.NETSqlClientclass,thefullrangeofoptionsandapproachestoperformingasynchronousdataaccessarenotincludedinthistopic.Formoreinformation,seeAsynchronousCommandExecutioninADO.NET2.0.

http://msdn.microsoft.com/en-us/library/ms379553(VS.80).aspx

AsynchronousAccessorExecution

TipsforUsingtheAsynchronousDataAccessMethodsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the Asynchronous Data Access Methods'%0AEntLib50_c6746013-4985-41c9-bf40-724e9a4fb787%0APlease provide details of the error you have located...%0A


ReturningDataasObjectsforClientSideQuerying

Developersoftenwanttoretrievedatainaformatthatbettermatchesthereal-worldobjectsthatthedatarepresents,ratherthanintherowsandcolumnsformatofaDataReaderorDataSet.ThisistypicallythecasewhenimplementingcommondesignpatternssuchasDomainModel,TableModule,andRepository.

TheDataAccessApplicationBlockincludessupportforthisscenariothroughaclasscalledanaccessor.Accessorsacceptinformationthatisrequiredtoextractthedata,andmappingsthatindicatehowtheinputparameterscorrespondtotheparametersoftheunderlyingquery.Theyuseoutputmappingsthatdefinehowthereturnedcolumnsmaptothepropertiesoftheobjectsthedeveloperwantstoworkwith,andreturnasequenceofobjectsofthespecifiedtype.Thefollowingschematicshowsthehighlevelprocesswhenusinganaccessortoretrievedataasanenumerablesequenceofobjects.

YoucanexecutebothstoredproceduresandSQLstatementsusingtheaccessorapproach.TheblockincludestheSprocAccessorclassforstoredprocedures

andtheSqlStringAccessorclassforexecutingSQLstatements.Accessorsalsoprovidemethodsforasynchronousdataretrievalwherethedatabaseyouareusingsupportsasynchronousqueryexecution.

Themappingmechanismisflexibleandextensible.ForstoredproceduresexecutedagainstSQLServerandOracledatabases,theaccessorwillattempttoresolvetheparametersautomaticallyifyoudonotspecifyaparametermapperthatdefinesthecorrelation.However,defaultparametermappingisnotavailablewhenusingSQLstatements,orforotherdatabasesandproviders.Inthesecases,youmustspecifyacustomparametermapperthatcanresolvetheparameters.

Note:Keepinmindthatcreatingstoredprocedureaccessorswiththedefaultmappermayberesourceintensiveandaffectperformance.Considercachingtheaccessorand/orthemapper.

Whenyouexecuteanaccessor,youcanprovideanoutputmappingthatindicateshowtheaccessorshouldmapthevaluesreturnedfromthedatabasetothepropertiesoftheobjectsitreturnstothecaller.Ifyoudonotspecifyanoutputmapper,theblockusesadefaultmapbuilderclassthatmapsthecolumnnamesofthereturneddatatopropertiesoftheobjectsitcreates.Alternatively,youcancreateacustommappingtospecifythecorrelationbetweencolumnsintherowsetandthepropertiesoftheobjects.

TheaccessorreturnsdataasasequenceofobjectsintheformIEnumerable<TResult>,whereeachobjectrepresentsonerowofdatainthedatasourceandexposespropertiesthatmaptothecolumnsineachrow.Youcanhandletheresultsinyourcodeasobjectsthatarepartofyourdatamodel,orquerythemusingclient-sidetechniquessuchasLanguageIntegratedQuery(LINQ).

Thefollowingshowsasimpleexampleofexecutingastoredprocedurethattakesnoparametersandthenqueryingtheresultsreturnedfromtheaccessor.ThecodeassumesyouhavedefinedtheCustomerclasselsewhere,andyouhaveresolvedaninstanceoftheDatabaseclassyouwanttouseandstoreditinthevariablenameddb.

C#

//Createanoutputrowmapperthatmapsallpropertiesbasedonthecolumnnames

IRowMapper<Customer>mapper=MapBuilder<Customer>.BuildAllProperties();

//Createastoredprocedureaccessorthatusesthisoutputmapper

varaccessor=db.CreateSprocAccessor("TopTenCustomers",mapper);

//Executetheaccessortoobtaintheresults

varcustomerData=accessor.Execute();

//Performaclient-sidequeryonthereturneddata

varresults=fromcustomerincustomerData

wherecustomer.State=="WA"

orderbycustomer.Name

selectnew{Name=customer.Name};

//Displaytheresults

foreach(varcustomerinresults)

{

Console.WriteLine("{0}isatopcustomerinWashingtonState",customer);

}

VisualBasic

'Createanoutputrowmapperthatmapsallpropertiesbasedonthecolumnnames

DimmapperAsIRowMapper(OfCustomer)=MapBuilder(OfCustomer).BuildAllProperties()

'Createastoredprocedureaccessorthatusesthisoutputmapper

Dimaccessor=db.CreateSprocAccessor("TopTenCustomers",mapper)

'Executetheaccessortoobtaintheresults

DimcustomerData=accessor.Execute()

'Performaclient-sidequeryonthereturneddata

Dimresults=FromcustomerIncustomerData_

Wherecustomer.State="WA"_

OrderBycustomer.Name_

SelectName=customer.Name

'Displaytheresults

ForEachcustomerInresults

Console.WriteLine("{0}isatopcustomerinWashingtonState",customer)

Next

Therearealsomethodsthatallowyoutopassparametersoraparametermappertotheaccessor,andexecuteaquerywithoutcreatinganaccessordirectly.Formoreinformationaboutusingaccessorstoretrievedataasobjects,seethefollowingtopics:

DefiningParameterMappersBuildingOutputMappersCreatingandUsingAccessorsExecutingQuerieswithoutCreatinganAccessorExecutingAccessorQueriesAsynchronouslyAdditionalInformationforAccessorsandClient-sideQueries

Note:TheaccessorfeatureintheDataAccessApplicationBlockisnotanObject/RelationalMapping(OR/M)mechanism,andshouldnottobeconfusedwithLINQtoSQL,oranyotherimplementationthatperformsoptimizationofqueries.Itdoesnotprovidesupportforupdates,identitymaps,foreignkeys,joins,orautomaticSQLgeneration.Thetechniqueforclient-sidequeriesmorecloselyresemblesthatofLINQtoObjects.However,thereisnoassumptiononhowyouwill(orcan)usethereturnedobjectgraphinyourapplications.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Returning Data as Objects for Client Side Querying'%0AEntLib50_5b8cd6ef-7aca-4435-bea6-427d4bfaac60%0APlease provide details of the error you have located...%0A


DefiningParameterMappers

AparametermappertakesthesetofobjectsyouwanttopasstoaqueryandconvertseachoneintoaDbParameterobject.Theaccessorassignstheseparameterstothecommandobjectitusestoaccessthedatasource.Forinformationaboutusingparametermapperswithanaccessor,seeCreatingandUsingAccessorsandExecutingQuerieswithoutCreatinganAccessor.

TheDataAccessApplicationBlockincludesadefaultparametermappingmechanism.ThismechanismmapsvaluesyouprovideasqueryparameterstotheDbParameterinstancesthequerywillusewhenexecutingagainstthedatabase.

Note:ThedefaultparametermappingmechanismisonlyavailablefortheSqlDatabaseandOracleDatabaseclasses,orforcustomdatabaseclassesyoucreatewherethedatabasesupportsparameterdiscovery.TheDatabaseclassexposesaBooleanpropertynamedSupportsParemeterDiscoverythatyourcodecantest(notethat,forbackwardcompatibilityreasons,themisspellingofthisnameispreservedinthecurrentversion).Ifyouuseanyotherdatabaseprovider,youmustcreateasuitableimplementationoftheIParameterMapperinterfacethatassignstheparametervaluestotheDbCommand.Formoreinformation,seeCreatingCustomParameterMapperslaterinthistopic.

Thisdefaultmappingusesthepositionoftheparametersyouprovideintheobjectarray,andexecutestheADO.NETDeriveParametersmethodtodiscovertheparametersrequiredbytheprocedure.Itmapsyourparameter(0)tothefirstparameteroftheprocedure,parameter(1)tothesecondparameteroftheprocedure,andsoon.ItconvertstheCLRtypesyouspecifyintotheappropriatedatabasetypesforeachDbParameteritpopulates.

TheADO.NETDeriveParameterscallthatresolvesparametersforastoredprocedurerequiresaround-triptothedatabase.Theapplicationblockprovidesparameterinformationcachingtomitigatetheperformancehitthatthisincurs.

Afterthefirstcalltoastoredprocedurethatrequiresparameterdiscovery,theinformationabouteachparameterissavedintheparametercache.Thismeansthatsubsequentcallstothesamestoredprocedurewillnotrequirearound-triptothedatabase.

CreatingCustomParameterMappersToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Defining Parameter Mappers'%0AEntLib50_f256ad70-9cdc-4404-8056-83be6fa9d1a2%0APlease provide details of the error you have located...%0A


BuildingOutputMappers

Anoutputmappertakestheresultsetreturnedfromadatabase(intheformofrowsandcolumns)andconvertsthedataintoasequenceofobjects.Therearetwodifferenttypesofoutputmappersthatyoucanusetotransformthereturneddata.Rowmapperstransformeachrowintoanobject,sothattheaccessorcanreturnasequenceoftheseobjects.Resultsetmapperstaketheentireresultsetandgenerateacompleteobjectgraphthatrepresentstheresultsetasobjects.

Thefollowingsectionsofthistopicprovidemoreinformationaboutthedefaultmappingcapabilitiesandthetwotypesofoutputmapper:

UsingtheDefaultRowMapperDefiningCustomRowMappingsCreatingResultSetMappers

Forinformationaboutusingoutputmapperswithanaccessor,seeCreatingandUsingAccessorsandExecutingQuerieswithoutCreatinganAccessor.

UsingtheDefaultRowMapper

DefiningCustomRowMappings

CreatingResultSetMappersToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Building Output Mappers'%0AEntLib50_9959e828-5ccd-4b63-81c2-509afe4393cd%0APlease provide details of the error you have located...%0A


CreatingandUsingAccessors

Accessorsexecutethequeryyouspecifyusingtheparametervaluesandaparametermapper(ifprovided),andtransformtheresultintoaseriesofobjectsusingtheoutputmapperyouspecify.YoucancreateanaccessorbycallingamethodonyourchosenimplementationoftheDatabaseclass,suchasSqlDatabaseorOracleDatabase,oryoucancreateanaccessordirectlyusingthenewoperatororthroughdependencyinjection.

Note:BecauseoftheoverheadassociatedwithsettingupAccessorsandtheirassociatedmappings,yougainimprovedperformancebycreatingtheaccessorinadvance,maintainingareferencetoit,andreusingtheinstance.Usingthistechniqueyouonlyincurthesetupcostonceinsteadofeverytimeyoucallthedatabase.

Thedifferencebetweenusingthedefaultmappersandprovidingyourownimplementationofthemapperinterfaces,IRowMapperandIResultSetMapper,isthatwhenprovidingyourownimplementationyoucangetbetterperformancethroughspecialcasecode,ordomoresophisticateddatatransformationsthanthedefaultcolumn-to-propertydirectmapping.Thecosthereisthetimetoimplementthatspecialcasecodeandthefuturemaintenanceburden.

TheDataAccessApplicationBlockprovidestwoaccessorsthatyoucanusetoretrievedataasobjects.Thefollowingsectionsofthistopicdescribeeachoneindetail:

StoredProcedureAccessorSQLStringAccessor

Seethefollowingtopicsformoreinformationaboutusingaccessorsinyourapplications:

DefiningParameterMappersBuildingOutputMappers

ExecutingQuerieswithoutCreatinganAccessorExecutingAccessorQueriesAsynchronouslyAdditionalInformationforAccessorsandClient-sideQueries

StoredProcedureAccessor

SQLStringAccessor




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating and Using Accessors'%0AEntLib50_17e750dc-a9dc-42ca-a9aa-d6a8c44d7d4e%0APlease provide details of the error you have located...%0A


ExecutingQuerieswithoutCreatinganAccessor

Insteadofcreatinganaccessorfirst,andthenexecutingit,youcanusethemethodsoftheDatabaseclasstocreateanaccessorandexecuteitasoneoperation.YoucandothiswithboththeSprocAccessorandSqlStringAccessor.ThemaindifferencebetweenthisapproachandcallingtheExecutemethodexplicitlyonanexistingaccessoristhatyoumustalsopassanyrequiredparametersintotheExecuteSprocAccessormethod.Thefollowingsectionsshowthetechniqueforthetwotypesofaccessor:

StoredProcedureAccessorSQLStringAccessor

Seethefollowingtopicsformoreinformationaboutusingaccessorsinyourapplications:

DefiningParameterMappersBuildingOutputMappersCreatingandUsingAccessorsExecutingAccessorQueriesAsynchronouslyAdditionalInformationforAccessorsandClient-sideQueries

StoredProcedureAccessor

SQLStringAccessorToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://msdn.microsoft.com/en-us/library/bb384665.aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Executing Queries without Creating an Accessor'%0AEntLib50_77b890cd-9282-4dc7-9004-5125f160552c%0APlease provide details of the error you have located...%0A


ExecutingAccessorQueriesAsynchronously

Youcanexecuteaccessorsasynchronouslyifyouwish,inmuchthesamewasasyoucanexecutemanyoftheothermethodsoftheDataAccessApplicationBlock.However,thisisonlypossiblewheretheunderlyingdatabasesupportsasynchronousoperations(inotherwords,theDatabase.SupportsAsyncpropertyistrue).

TheSprocAccessorandSqlStringAccessorclassesexposetheBeginExecutemethod,whichtakesasparametersareferencetoacallbackmethodthatwillexecutewhentheoperationends,aparameterthatcontainsstateyouwanttopasstothecallbackmethod,andanobjectarraycontainingtheparametervaluestheaccessorwillusewhenitexecutesthequery.TypicallyyouwillpassareferencetotheaccessorastheasynchronousstateparametersothatyoucancalltheEndExecutemethodonitwithinthecallbackmethod.

TheaccessorsexposeonlyasingleoverloadoftheBeginExecutemethod.YoucancreatetheaccessorusinganyofthetechniquesdescribedinthetopicCreatingandUsingAccessors.

Whenthequeryoperationcompletes,thecodeinthecallbackhandlerexecutesandyoucanretrievetheaccessorandcalltheEndExecutemethodtoretrievetheIEnumerablesequenceastheresult.Thefollowingcodeshowsanexampleofusingasynchronousoperationswithanaccessor.Noticethattheconnectionstringspecifiesaconnectionthatsupportsasynchronousoperations.Inaddition,keepinmindthattheconnectionisnotcloseduntiltheentirelistisprocessed.YoumustforcecompleteevaluationoftheresultsequencetoextractallofthedatawhenyoucalltheEndExecutemethod.Forexample,calltheToListmethod,asshowninthefollowingcodeextract.C#

StringconnectionString

=@"server=(local);database=Northwind;IntegratedSecurity=true;AsynchronousProcessing=true";

SqlDatabasedb=newSqlDatabase(connectionString);

DbCommandcmd=db.GetStoredProcCommand("SomeProcedureName");

try

{

//Createtheaccessor.Thisexampleusesthesimplestoverload.

varaccessor=db.CreateSprocAccessor<Customer>("TopTenCustomers");

//Executetheaccessorasynchronously,passinginthecallbackhandler,

//theexistingaccessorastheAsyncState,andtheparametervalues.

IAsyncResultasync=accessor.BeginExecute(MyEndExecuteCallback,accessor,2009,"WA");

}

catch

{

//...

//handleanyexecutioninitiationerrorshere

}

//================================================

//callbackhandlerthatexecuteswhencallcompletes

publicvoidMyEndExecuteCallback(IAsyncResultasync)

{

try

{

//obtaintheresultsfromtheaccessor

DataAccessoraccessor=async.AsyncStateasDataAccessor<Customer>;

varcustomers=accessor.EndExecute(async).ToList();

//...

//usetheresultshere

//...

}

catch

{

//...

//handleanyexecutioncompletionerrorshere

}

}

VisualBasic

DimconnectionStringAsString_

="server=(local);database=Northwind;IntegratedSecurity=true;AsynchronousProcessing=true"

DimdbAsNewSqlDatabase(connectionString)

DimcmdAsDbCommand=db.GetStoredProcCommand("SomeProcedureName")

Try

'Createtheaccessor.Thisexampleusesthesimplestoverload.

Dimaccessor=db.CreateSprocAccessor(OfCustomer)("TopTenCustomers")

'Executetheaccessorasynchronously,passinginthecallbackhandler,

'theexistingaccessorastheAsyncState,andtheparametervalues.

DimasyncAsIAsyncResult_

=accessor.BeginExecute(AddressOfMyEndExecuteCallback,accessor,2009,"WA")

Catch

'...

'handleanyexecutioninitiationerrorshere

EndTry

'================================================

'callbackhandlerthatexecuteswhencallcompletes

PublicSubMyEndExecuteCallback(asyncAsIAsyncResult)

Try

'obtaintheresultsfromtheaccessor

DimaccessorAsDataAccessor=TryCast(async.AsyncState,DataAccessor(OfCustomer))

Dimcustomers=accessor.EndExecute(async).ToList()

'...

'usetheresultshere

'...

Catch

'...

'handleanyexecutioncompletionerrorshere

EndTry

EndSub

AnalternativeapproachtocodingthecallbackistousealambdafunctiondeclaredwithinthecalltotheBeginExecutemethodoftheAccessor.

Note:Therearesomelimitationsonusingasynchronousdataoperations,andseveralissuesyoushouldbeawareof.Formoredetails,seeUsingtheAsynchronousDataAccessMethods.

Inaddition,whenyouexecuteanaccessorasynchronously,youcanonlyiterateovertheresultsetonce.Ifyouattempttoiterateoveritagain,theblockwillraiseanexception.Forthisreason,youmayneedtouseanapproachsuchastheToListmethodtoforcecompleteevaluationoftheresultsequence.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Executing Accessor Queries Asynchronously'%0AEntLib50_c47c18f7-8d38-4ee8-b8a5-ef8a29807372%0APlease provide details of the error you have located...%0A


AdditionalInformationforAccessorsandClient-sideQueries

Thistopicdescribessomeadditionalfactorsandissuesrelatedtousingaccessorstoretrievedataasasequenceofobjects.Itcoversthefollowing:

CreatingAccessorsthroughDependencyInjectionAccessingandIteratingtheResultsSetQueryingtheResultsSetUsingLINQDeferredLoadingandMultipleIterationsoftheResultSet

CreatingAccessorsthroughDependencyInjection

AccessingandIteratingtheResultsSet

http://msdn.microsoft.com/en-us/library/19e6zeyy.aspx

QueryingtheResultsSetUsingLINQ


DeferredLoadingandMultipleIterationsoftheResultSetToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Additional Information for Accessors and Client-side Queries'%0AEntLib50_47bc2264-1da1-4771-b611-029a23775874%0APlease provide details of the error you have located...%0A


CreatingPortableDatabaseApplications

Thereareissuesthatyoumustconsiderifyourapplicationmustworkwithmultipledatabasetypes.

WorkingwithOracleDatabases

SuggestionsforCreatingPortableDatabaseApplicationsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Portable Database Applications'%0AEntLib50_59250b69-2ea5-4ff1-99de-fc26e9569371%0APlease provide details of the error you have located...%0A


HandlingExceptions

Strategiesforhandlingexceptionsareessentialinanyenterpriseapplication.ThefollowinginformationwillhelpyouincorporatetheDataAccessApplicationBlockintoyourapproachtomanagingexceptions:

Theapplicationblockusesconfigurationinformation,whichmayresultinconfiguration-relatedexceptions.TheDatabasemethodsusebothADO.NETandtheunderlyingdatabaseprovider.ExceptionsthrownbyADO.NETarecaughtbytheDataAccessApplicationBlockforinstrumentationpurposes,andthentheyarere-thrown.Adequatelyprocessinganexceptionoftenrequiresaccesstothespecificexceptiontype.YoucanincludeacatchstatementforaspecificdatabaseproviderexceptionsuchasSqlException.However,databaseprovider–specificexceptiontypesarenotportableacrossdifferentproviders.

IfyouuseExecuteReaderwithinatryblock,youshouldaddafinallystatementandclosethereturnedDataReaderobject,asshowninthefollowingexample.ItassumesthatyouhaveresolvedtheDatabaseclassyourequireandstoredareferenceinthevariablenameddb.Formoreinformationoninstantiatingobjects,seeCreatingandReferencingEnterpriseLibraryObjects.C#

DbCommandcmd=db.GetStoredProcCommand("GetProductsByCategory");

IDataReaderreader=null;

try

{

//...

reader=db.ExecuteReader(cmd);

}

catch(Exceptionex)

{

//Processexception

}

finally

{

if(reader!=null)

reader.Close();

}

VisualBasic

DimcmdAsDbCommand=db.GetStoredProcCommand("GetProductsByCategory")

DimreaderAsIDataReader=Nothing

Try

'...

reader=db.ExecuteReader(cmd)

CatchexAsException

'Processexception

Finally

If(NotreaderIsNothing)Then

reader.Close()

EndIf

EndTry

Alternatively,youcanincludetheusingstatementtodisposeoftheDataReaderobject,whichcausesittoclose,asshowninthefollowingexample.C#

DbCommandcmd=db.GetStoredProcCommand("GetProductsByCategory");

using(IDataReaderreader=db.ExecuteReader(cmd))

{

//Processresults

}

VisualBasic

DimcmdAsDbCommand=db.GetStoredProcCommand("GetProductsByCategory")

UsingreaderAsIDataReader=db.ExecuteReader(cmd)

'Processresults

EndUsing

Fordesignandimplementationguidelinesforexceptionmanagementin.NET,seetheDesignGuidelinesforExceptions.


HandlingAsynchronousDataAccessExceptionsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Handling Exceptions'%0AEntLib50_5f1dcd7c-b3fa-468f-864d-62d3bac68f84%0APlease provide details of the error you have located...%0A


HandlingParameters

Moststoredproceduresacceptparameterswhosevaluesareeitherusedasinputtothestoredprocedureoraresetduringoutput.AswithADO.NET,theDataAccessApplicationBlockallowsdeveloperstoexplicitlyspecifyalloftheattributesofaparameter.Theseattributescanincludedirection,datatype,andlength.Thisapproachisnamedexplicitparameterhandling.However,asaconvenience,youcanspecifyonlythevalueswhenusinginputparameters.Inthiscase,theapplicationblockwilllookupandsupplytheparameterattributes.Thisapproachisnamedparameterdiscovery.

ExplicitParameterHandling

UsingColumnValuesasParameterInputs

ParameterDiscovery

OptionalParametersToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Handling Parameters'%0AEntLib50_d40074bc-fc16-4a1c-8856-60c515e11f3e%0APlease provide details of the error you have located...%0A


KeyScenarios

Thistopicdescribesthemostcommonsituationsdevelopersmustaddresswhenaccessingadatabase.Eachscenarioexplainsthetask,describesareal-worldsituationwheresuchataskmightarise,andincludescodedemonstratinghowtousetheDataAccessApplicationBlocktocompletethetask.Thescenariosareasfollows:

UsingaDbDataReadertoRetrieveMultipleRows.ThisscenarioillustrateshowyoucanusetheExecuteReadermethodtoretrievemultiplerowsofdatafromadatabasefordisplayintabulatedform—withoutexplicitlycachingthedata,usingaDataSetobjecttomanipulateit,orpassingittoothercomponentswithinyourapplication.Inotherwords,itillustrateshowtodisplaytheresultsasquicklyaspossible.UsingaDataSettoRetrieveMultipleRows.ThisscenarioillustrateshowyoucanusetheExecuteDataSetmethodtopassdatabetweenthecomponentsandthetiersofamulti-tierapplication.Thedataconsistsofoneormoredatatablesand,optionally,therelationshipsthatlinkthetablestogether.ExecutingaCommandandAccessingOutputParameters.ThisscenarioillustrateshowyoucanusetheExecuteNonQuerymethodtoretrieveasinglerowthatcontainsmultiplecolumnvalues.ExecutingaCommandandAccessingaSingleItemResult.ThisscenarioillustrateshowyoucanusetheExecuteScalarmethodtoperformasingle-itemlookup.PerformingMultipleUpdatesWithinaTransaction.ThisscenarioillustrateshowyoucanusetheExecuteNonQuerymethodfromwithinatransactiontoperformmultipleoperationsagainstadatabase,whereitisessentialthateitheralloperationssucceedornonesucceed.UsingaDataSettoUpdateaDatabase.Thisscenarioillustrateshow,afterchangingaDataSetobject,youcanusetheUpdateDataSetmethodtoupdatethedatabaseandmakeyourchangespermanent.RetrievingMultipleRowsasXML.ThisscenarioillustrateshowyoucanusetheExecuteXmlReadermethodtoretrievedatafromaSQLServerandhavethatdatareturnedinXMLformat.RetrievingDataasObjects.Thisscenariodemonstrateshowyoucanuse

thedataaccessorsincludedintheblocktoretrievedataasasequenceofobjectsofaspecifiedtypefromthedatastore.PerformingAsynchronousDataAccess.ThisscenariodemonstrateshowyoucanusetheasynchronousversionoftheExecuteReadermethodtoreaddatafromadatastoreasynchronously,andthenaccesstheresultsusingacallbackthatindicateswhenthemethodcompletes.

ThistopichelpsyouimplementyourapproachbyusingtheDataAccessApplicationBlock.Itdoesnothelpyouchoosethecorrectapproachforyourparticularsituation(forexample,itdoesnothelpyouchoosebetweenaDataSetandaDbDataReader).Forguidanceonapproachestodataaccess,seethefollowingMicrosoftpatterns&practicesguides:

.NETDataAccessArchitectureGuideINFO:MicrosoftGuideforDesigningDataTierComponentsandPassingDataThroughTiersImproving.NETApplicationPerformanceandScalability




http://support.microsoft.com/default.aspx?scid=kb;en-us;829025



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Key Scenarios'%0AEntLib50_da669e93-7f2a-4e21-b46f-ac4cf2241aea%0APlease provide details of the error you have located...%0A


UsingaDbDataReadertoRetrieveMultipleRows

Acommondatabasetaskistoretrieveanddisplayinformation.Forexample,anonlineretailapplicationmayneedtodisplayalistofproductswithinaspecifiedcategory.

TypicalGoals

Solution

UsingExecuteDataReader




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using a DbDataReader to Retrieve Multiple Rows'%0AEntLib50_ae92b94c-9b51-47d9-b861-718dcaa4d94c%0APlease provide details of the error you have located...%0A


UsingaDataSettoRetrieveMultipleRows

Inamulti-tiersystem,youmayneedtopassdatafromadataaccesscomponenttoamiddle-tierbusinesscomponent.Thedataisretrievedfromthedatabaseandsentback,throughthedataaccesslayer,tothebusinesslayer.TheinformationiscontainedintheDataSetobject.

TypicalGoals

Solution

UsingExecuteDataSet




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using a DataSet to Retrieve Multiple Rows'%0AEntLib50_2ca2db64-8b10-4c26-bb40-6201d4a590f8%0APlease provide details of the error you have located...%0A


ExecutingaCommandandAccessingOutputParameters

Acommondatabasetaskistoretrievespecific,multiple-columnvalues.Forexample,inaWeb-basedonlineretailapplication,youmaywanttoretrievefullproductdetailsforacertainproductinresponsetoauserrequest.

TypicalGoals

Solution

UsingExecuteNonQuery




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Executing a Command and Accessing Output Parameters'%0AEntLib50_cad8e344-87df-4e36-8e89-79c3a86df993%0APlease provide details of the error you have located...%0A


ExecutingaCommandandAccessingaSingleItemResult

Therearemanysituationsinwhichyouhavetoperformasingle-itemlookup.Forexample,anonlineretailermaywanttouseaproductIDtoretrieveaproductnameoruseacustomerIDtoretrieveacreditrating.

TypicalGoals

Solution

UsingExecuteScalar





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Executing a Command and Accessing a Single Item Result'%0AEntLib50_5b9d82a7-9b4d-4954-bfd8-f9bc1f1c9186%0APlease provide details of the error you have located...%0A


PerformingMultipleUpdatesWithinaTransaction

Whenanapplicationexecutesmultipleoperationsagainstadatabase,acommonrequirementisthatalloftheoperationsmustsucceedorthedatabasemustrollbacktoitsoriginalstate(thatis,itsstatebeforetheoperationsbegan).Thisall-or-nothingrequirementisreferredtoasatransaction.Transactionsensuretheintegrityofadatabasesystem'sstate.Forexample,inaclassicbankingscenario,anapplicationmustdebitoneaccountandcreditanotherwithaparticularamountofmoney.Forproperaccounting,itisessentialthateitherbothoperationssucceedorneitheroperationsucceeds.Thismeansthatbothoperationsshouldbeperformedinthecontextofasingletransaction.

TypicalGoals

Solution

UsingExecuteNonQueryinaTransactionToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Performing Multiple Updates Within a Transaction'%0AEntLib50_23a1ec97-3c89-4240-bb49-fb1ca1bd843f%0APlease provide details of the error you have located...%0A


UsingaDataSettoUpdateaDatabase

Databasesmustbeperiodicallyupdatedwithnewinformation.Forexample,inaWeb-basedonlineretailapplication,youmaywanttoaddanewcustomertothedatabase,modifythenameassociatedwithacustomerID,ordeleteacustomerrecordentirely.

TypicalGoals

Solution

UsingUpdateDataSet




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using a DataSet to Update a Database'%0AEntLib50_4d4d3a93-8b1c-4a98-a8e7-2437abf49689%0APlease provide details of the error you have located...%0A


RetrievingMultipleRowsasXML

AnexampleofwhereyoumaywanttouseXMLdataiswithinane-commerceapplicationthatallowsclientstorequestaproductcatalogthatisinXMLformat.

TypicalGoals

Solution

UsingExecuteXmlReader




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Retrieving Multiple Rows as XML'%0AEntLib50_02794a88-b67a-412b-b77e-f2798bcc28ca%0APlease provide details of the error you have located...%0A


RetrievingDataasObjects

Thisscenariodemonstratesoneofthewaysthatyoucanusethedataaccessorsprovidedwiththeblocktoreaddatafromadatastoreandreturnitasasequenceofobjectsofthetypeyouspecify.TheDataAccessApplicationBlockprovidestwotypesofaccessors,forstoredproceduresorforusewithSQLstatements,inadditiontoarangeofclassesthathelpyoutomapparameterstothequeryandmapthereturneddatatothetypeofobjectyourequire.Forinformationabouttheseclasses,seeReturningDataasObjectsforClientSideQuerying.

TypicalGoals

Solution





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Retrieving Data as Objects'%0AEntLib50_d093c4ad-fcdd-4b66-a6b3-00521c681c90%0APlease provide details of the error you have located...%0A


PerformingAsynchronousDataAccess

ThisscenariodemonstrateshowyoucanusetheasynchronousversionoftheExecuteReadermethodtoreaddatafromadatastoreasynchronously,andthenaccesstheresultsusingacallbackthatindicateswhenthemethodcompletes.YoudothisusingtheBeginExecutereaderandEndExecuteReadermethodsoftheDatabaseclass.

Note:AsynchronousdataaccessisnotsupportedbyallADO.NETdataproviders.TheDatabaseclassexposesaBooleanpropertynamedSupportsAsyncthatyoucantesttocheckatruntimeifasynchronousoperationsaresupported.Ifthispropertyreturnsfalse,anyasynchronousmethodsyoucallwillthrowanInvalidOperationException.InEnterpriseLibrary5.0,theonlydatabasetypethatsupportsasynchronousoperationistheSqlDatabaseclass.

TypicalGoals

Solution


UsingBeginExecuteReaderandEndExecuteReaderwithaCallback




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Performing Asynchronous Data Access'%0AEntLib50_0cc9f22e-d057-44ad-ae33-b66302841947%0APlease provide details of the error you have located...%0A


DesignoftheDataAccessApplicationBlock

TheDataAccessApplicationBlockincludesthefollowingfeatures:Asimpleandefficientwayofworkingwithdifferentdatabasesystems(seeDesigningforSimplifiedDataAccess)Awayofdevelopingdatabase-agnosticapplications(seeDesigningforDatabase-AgnosticApplications)Aneasywaytoadjustandvalidatethedatabaseconfigurationsettings

DesignGoals

DesignHighlightsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Data Access Application Block'%0AEntLib50_171e0be4-f2d4-40a4-b5c8-158258c8c807%0APlease provide details of the error you have located...%0A


DesigningforSimplifiedDataAccess

Developersfacemanyimplementationchoicesandrequirementswhentheybuilddataaccesssolutions.Theymustaccessthedatainavarietyofways,andtheirsolutionsmustworkwithdifferenttypesofdatabases,eachofwhichhandlesdataaccessdifferently.Asaresult,developersmayfindthemselvesduplicatingcodethatperformscommontasks,suchasmanagingconnectionsandassigningparameterstocommands.

Anotherchallengeismaintainingaconsistentapproachinhowdataaccessoperationsareimplemented.Itmaybenecessarytomaintainthisconsistencyacrosssingleprojects,multipleprojects,orenterprise-scalesolutions.Uniformmethodsofdataaccessmakethecodeeasiertounderstand,morepredictable,andeasiertomaintain.

TheDataAccessApplicationBlocksimplifiesdataaccessbyencapsulatingthelogicthatperformscommondatabaseoperations.Thesemethodsalsohandlecommonhousekeepingtaskssuchasopeningandclosingconnections.Theyaredatabase-agnostic,whichmeansthattheyworkwithSQLServerandOracledatabasesanddonotrequiremodificationtodoso.Applicationswrittenforonetypeofdatabaseusethesamemethodsasthosewrittenforanothertypeofdatabase.Thismeansthatapplicationsareconsistentinthewaysthattheyaccessdata.Inaddition,theGenericDatabaseclasssupportsmanyofthesesamefeaturesacrossADO.NETdataproviders.

DesignImplications




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Designing for Simplified Data Access'%0AEntLib50_28c11fee-5ad6-4efa-a347-7d6644587ffc%0APlease provide details of the error you have located...%0A


DesigningforDatabase-AgnosticApplications

TheDataAccessApplicationBlockprovidesanextensibleframeworkforsupportingmultipletypesofrelationaldatabases.Applicationsthatusetheapplicationblockareportableacrossdifferentdatabasesystems.

Thereareanumberofgeneraldataaccesstools—suchasOpenDatabaseConnectivity(ODBC)orOLEDB—thatcanprovideaccesstoavarietyofdatasources.Onedrawbacktothesetoolsisthathowtheyareuseddependsonthetargetdatabase.Thatmeansthatprogrammersneedtounderstandvariousprogrammingmodelstoaccessdifferentdatabasetypes.Movinganapplicationtoadifferentdatabasecouldrequireasignificantamountofrecoding.

AnotherdrawbacktotheODBCorOLEDBapproachisthatperformancemaysuffer.Genericdataprovidersareslowerthanthoseoptimizedforaparticulardatasource.TheDataAccessApplicationBlockprovidesanimplementationthatfeaturesbothportabilityandoptimizedperformance.

CopyCode

CopyCode

AbstractionoftheDatabaseSystemTheDataAccessApplicationBlockbuildsonthecapabilitiesprovidedbyADO.NETtocreateadatabase-agnosticprovidermodel.Thefollowingaresomeofthefeaturesitprovides:

Itstandardizesparameternames.Forexample,itsuppliesthe"@"characterforSQLparameternames.ItconfiguresthestoredprocedurepackagenamemappingforOracledatabases.ItusesADO.NETstaticmethodsforSQLServerandOracletosupportagnosticparameterdiscovery.ItaddsthecursorparameterforresultsreturnedbyanOraclestoredprocedure.

ThemajorityofthedataaccessmethodsareavailablethroughtheabstractDatabaseclass.ClientcodecanrefertothesemethodsintheircoderegardlessoftheactualDatabase-derivedobjectused.Forexample,thefollowingcodeshowshowtousetheExecuteDataSetmethod.C#

Databasedb;

...

db.ExecuteDataSet(cmd);

VisualBasic

DimdbAsDatabase

...

db.ExecuteDataSet(cmd)

TheblockcreatesthespecificDatabase-derivedobject.ItreturnsanobjectoftypeDatabase,thusallowingtheclientcodetoremaingenericregardingtheactualdatabasetypereturned.

ThemethodsavailableontheDatabaseclassrequireinformationaboutthecommandtobeexecutedaswellasanyassociatedparameters.Different

databasesystemshandlecommandsandparametersindifferentways.Database-derivedclassesprovidemethodsthatacceptparameterinformation;thespecificdatabasesystemsprovidetheirownderivedimplementationstohandleparameterparameters.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Designing for Database-Agnostic Applications'%0AEntLib50_7124456c-f9fd-4b11-bb27-9bdf9cb3d82b%0APlease provide details of the error you have located...%0A


ExtendingandModifyingtheDataAccessApplicationBlock

Initsoriginalstate,theDataAccessApplicationBlockworkswellfortypicaldataaccessscenarios.However,theremaybetimeswhenyouneedtocustomizesomeoftheapplicationblock'sbehaviortobettersuityourapplication'srequirements.YoucanextendtheDataAccessApplicationBlockusingthebuilt-inextensionpoints.Youcanalsomodifytheapplicationblockbymakingchangestoitssourcecode.Formoredetails,seethefollowingtopics:

ExtendingtheDataAccessApplicationBlockExtendingandModifyingEnterpriseLibrary




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying the Data Access Application Block'%0AEntLib50_50b1d864-39c9-46f2-89a8-9fceea5db05e%0APlease provide details of the error you have located...%0A


ExtendingtheDataAccessApplicationBlock

Youextendtheapplicationblockthroughdesignatedextensionpoints.Typically,thesearecustomclassesthatyoumustwrite.Thecustomclassesimplementaparticularinterfaceorderivefromanabstractclass.Becausethesecustomclassesexistinyourapplicationspace,youdonothavetomodifyorrebuildtheapplicationblock.Instead,youuseconfigurationsettingstodesignateyourextensions.

Currently,youcanextendtheapplicationblockbyaddinganewdatabasetype.Youwoulddothisifyourapplicationneedsdatabase-specificfeaturesfromadatabaseotherthantheSQLServerdatabaseortheOracledatabase.Youonlyneedtoextendtheapplicationblockiftheapplicationblock'sGenericDatabaseclassandtheADO.NETdataproviderforthedatabasesystemdonotprovidethefeaturesyourequire.Forexample,theGenericDatabaseobjectdoesnotsupportspecialparameterprefixesforstoredproceduresorinvokemethodsthatarenotontheDbCommandclassortheDbConnectionclass.Inaddition,theGenericDatabaseclassdoesnotsupportparameterdiscovery.

YoucouldextendtheapplicationblockbycreatinganewdatabaseclassthatsupportsfeaturesnotexposedbytheADO.NETdataprovider.Forexample,yourdatabaseclasscouldsupportparameterdiscovery.Youcouldalsoextendtheapplicationblocktoallowyourclientcodetoremaindatabase-agnosticthroughtypeconversionsorbymanagingSQLsyntaxconversions.BuildingacustomdatabaseclassallowsyourapplicationtosupporttheentireDataAccessApplicationBlockAPIsetandtobemorecompatiblewiththesyntaxesofotherdatabases.Tolearnmore,seeAddingaNewApplicationBlockDatabaseProvider.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending the Data Access Application Block'%0AEntLib50_31e0ccfc-7da3-4ff9-af9b-d377de75fd7e%0APlease provide details of the error you have located...%0A


AddingaNewApplicationBlockDatabaseProvider

Iftherelationaldatabasesystemyouareusingdoesnotalreadyhaveanapplicationblockdatabaseprovider,youcancreateyourown.Thisisonlynecessaryiftheapplicationblock'sGenericDatabaseclassdoesnotmeettherequirementsofyourapplication.(ThisassumesthatthereisanADO.NETDbProviderFactorytypeforthedatabasesystemyouareusing.)Tocreateanewdatabaseprovider,youmustcreateanewdatabaseclassthatderivesfromtheDatabaseclass.Additionally,ifyouwantyourclientcodetoremaindatabase-agnostic,youmighthavetowriteadditionalcodetoperformsuchtasksastypeconversion.

CreatingaNewDatabaseClass

ConfiguringYourApplicationtoUsetheNewProvider

RecommendationsforCreatingaDatabaseProviderToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding a New Application Block Database Provider'%0AEntLib50_e4b62b4c-1b44-4433-8958-dc8dc9d4c9f0%0APlease provide details of the error you have located...%0A



Twoofanadministrator'smaintaskswillbetoseethattheinitialdeploymentoftheDataAccessApplicationBlockisplannedandmanagedandthatsubsequentupdatesaredeployedwithminimalimpacttoexistingapplicationsthatusetheapplicationblock.FordetailsofdeployingandupdatingEnterpriseLibraryandtheapplicationblocks,seeDeployingEnterpriseLibrary.

Inaddition,administratorsmustdecidewhethertheywanttousetheinstrumentationexposedbytheapplicationblock.Fordetailsofhowtoenableanddisableinstrumentation,seeEnablingInstrumentation.ForinformationabouttheinstrumentationcontainedwithintheDataAccessApplicationBlock,seethefollowingtopics:

DataAccessApplicationBlockPerformanceCountersDataAccessApplicationBlockEventLogEntries




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deployment and Operations'%0AEntLib50_bde72f4b-38f3-4ee3-95c4-6fb76d5279bc%0APlease provide details of the error you have located...%0A


DataAccessApplicationBlockPerformanceCounters

ThefollowingtabledescribestheDataAccessApplicationBlockperformancecounters.

PerformanceCounterName

Description

CommandsExecuted/sec

Therateatwhichdatabasecommandswereexecuted.

CommandsFailed/sec Therateatwhichdatabasecommandsfailedtoexecute.

ConnectionsFailed/sec Therateatwhichdatabaseconnectionsfailedtoopen.

ConnectionsOpened/sec

Therateatwhichdatabaseconnectionswereopened.

TotalCommandsExecuted

Thetotalnumberofdatabasecommandsthatwereexecuted.

TotalCommandsFailed Thetotalnumberofdatabasecommandsthatfailedtoexecute.

TotalConnectionsFailed

Thetotalnumberofdatabaseconnectionsthatfailedtoopen.

TotalConnectionsOpened

Thetotalnumberofdatabaseconnectionsthatwereopened.

Aratecountersamplesanincreasingcountofeventsovertimeanddividesthevaluesbythechangeintimetodisplayarateofactivity.Formoreinformationaboutperformancecounters,seeOverviewofPerformanceMonitoringonTechNet.




[email protected].


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Data Access Application Block Performance Counters'%0AEntLib50_68ab9e29-a8f6-47ef-a9ab-a6480c5896c4%0APlease provide details of the error you have located...%0A


DataAccessApplicationBlockEventLogEntries

TheDataAccessApplicationBlockisinstrumentedtologentriestotheapplicationeventlogforavarietyofevents.ThistopicliststheDataAccessApplicationBlockeventlogentries.

ConnectionFailedEvent

CommandExecutedEvent

CommandFailedEvent

DataConfigurationFailureEventToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Data Access Application Block Event Log Entries'%0AEntLib50_a4176519-a574-4e38-baf6-98baa5c71293%0APlease provide details of the error you have located...%0A


TheExceptionHandlingApplicationBlock

TheEnterpriseLibraryExceptionHandlingApplicationBlockhelpsdevelopersandpolicymakersimplementcommondesignpatternsandcreateaconsistentstrategyforprocessingexceptionsthatoccurinallarchitecturallayersofanenterpriseapplication.Itisdesignedtosupportthetypicalcodecontainedincatchstatementsinapplicationcomponents.Insteadofrepeatingthiscode(suchascodethatlogsexceptioninformation)inidenticalcatchblocksthroughoutanapplication,theExceptionHandlingApplicationBlockallowsdeveloperstoencapsulatethislogicasreusableexceptionhandlers.TheExceptionHandlingApplicationBlockincludesfourexceptionhandlers:

Wraphandler.Thisexceptionhandlerwrapsoneexceptionaroundanother.Replacehandler.Thisexceptionhandlerreplacesoneexceptionwithanother.Logginghandler.Thisexceptionhandlerformatsexceptioninformation,suchasthemessageandthestacktrace.ThenthelogginghandlerpassesthisinformationtotheEnterpriseLibraryLoggingApplicationBlocksothatitcanbepublished.FaultContractexceptionhandler.ThisexceptionhandlerisdesignedforuseatWindows®CommunicationFoundation(WCF)serviceboundaries,andgeneratesanewFaultContractfromtheexception.

YoucanextendtheExceptionHandlingApplicationBlockbyimplementingcustomhandlers,andadministratorscanmanagetheconfigurationoftheblockto,forexample,turnonadditionaldebugginginstrumentationorchangethebehavioroftheblockinlinewithchangestobusinessrequirements.TheconfigurationcanevenbemanagedusingGroupPolicytools.

ThissectionincludesthefollowingtopicsthatwillhelpyoutounderstandandusetheExceptionHandlingApplicationBlock:

WhatDoestheExceptionHandlingApplicationBlockDo?Thistopicprovidesabriefoverviewthatwillhelpyoutounderstandwhattheblockcando,andexplainssomeoftheconceptsandfeaturesitincorporates.Italsoprovidesasimpleexampleofthewaythatyoucanwritecodetousetheblock.

WhenShouldIUsetheExceptionHandlingApplicationBlock?Thistopicwillhelpyoutodecideiftheblockissuitableforyourrequirements.Itexplainsthebenefitsofusingtheblock,andanyalternativetechniquesyoumayconsider.Italsoprovidesdetailsofanylimitationsoftheblockthatmayaffectyourdecisiontouseit.DevelopingApplicationsUsingtheExceptionHandlingApplicationBlock.ThistopicexplainshowtoconfiguretheExceptionHandlingApplicationBlock,howtoaddtheblocktoyourapplications,howtodetermineappropriateexceptionhandlingpolicies,howtospecifydifferenthandlingactions,andhowtosendanexceptiontotheExceptionHandlingBlock.KeyScenarios.ThistopicshowsdifferentwaystousetheExceptionHandlingApplicationBlockinyourownapplications.DesignoftheExceptionHandlingApplicationBlock.Thistopicexplainsthedecisionsthatwentintodesigningtheblockandtherationalebehindthosedecisions.ExtendingandModifyingtheExceptionHandlingApplicationBlock.Thistopicexplainshowtoextendtheapplicationblockbyaddingcustomhandlersandformatters.Italsogivessomeadviceabouthowtomodifythesourcecode.DeploymentandOperations.Thistopicexplainshowtodeployandupdatetheblockassemblies.

MoreInformationFormoreinformation,seethefollowingMicrosoft®patterns&practicesguides:

ApplicationArchitecturefor.NET:DesigningApplicationsandServicesDesignGuidelinesforExceptions






mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Exception Handling Application Block'%0AEntLib50_cd0fa4e8-4a99-4490-8662-ec9d1ade4b28%0APlease provide details of the error you have located...%0A


WhatDoestheExceptionHandlingApplicationBlockDo?

Arobustandwell-plannedexceptionhandlingstrategyisavitalfeatureofyourapplicationdesignandimplementationthatwillhelpyouavoidriskssuchasexposingerrormessagescontainingsensitiveinformation,orleavingyourapplicationandsystemsinaninconsistentstateandopentoattackwhenanerroroccurs.

Anexceptionhandlingstrategyconsistsofaseriesofpoliciesthatdefinehowyouwillpresentclearandappropriatemessagestousersandhowyoucanprovideassistanceforoperators,administrators,andsupportstaff.Acomprehensiveexception-handlingstrategywillusually:

NotifytheuserwithafriendlymessageStoredetailsoftheexceptioninaproductionlogorotherrepositoryAlertthecustomerserviceteamtotheerrorAssistsupportstaffincross-referencingtheexceptionandtracingthecause

TheExceptionHandlingApplicationBlockcanhelpyoutodefineandcreateconsistentexceptionmanagementstrategiesbyimplementingthreewell-knowndesignpatterns:

ExceptionShielding.Thispatternensuresthatyourapplicationdoesnotleaksensitiveinformation,nomatterwhatrun-timeorsystemeventmayoccurtointerruptnormaloperation.Andonamoregranularlevel,itcanpreventyourassetsfrombeingrevealedacrosslayer,tier,process,orserviceboundaries.ExceptionLogging.Thispatterncanhelpyoutodiagnoseandtroubleshooterrors,audituseractions,andtrackmaliciousactivityandsecurityissuesbyloggingdetailsofexceptionsanderrorsthatoccur.ExceptionTranslation.Thispatterndescribeshowyoucanwrapexceptionswithinotherexceptionsspecifictoalayertoensurethattheyactuallyreflectuserorcodeactionswithinthelayeratthattime,andnotsomemiscellaneousdetailsthatmaynotbeuseful.

TheExceptionHandlingApplicationBlockletsyouassociateexceptiontypeswithnamedpolicies.Youdothisbyusingtheconfigurationtools.Policiesspecifytheexceptionhandlersthatexecutewhentheblockprocessesa

particularexceptiontype.Exceptionhandlersare.NETclassesthatencapsulateexceptionhandlinglogicandimplementtheExceptionHandlingApplicationBlockinterfacenamedIExceptionHandler.

Youcanchainthesehandlerstogethersothataseriesofthemexecutewhentheassociatedexceptiontypeishandled.Thefollowingaresomeexamplesofnamedpoliciesanddescriptionsofwhattheymightprovide:

Basepolicy.Thispolicylogstheexceptionandre-throwstheoriginalexception.Securepolicy.Thispolicylogstheexception,replacestheoriginalexceptionwithacustomexception,andthrowsthenewexception.Expressivepolicy.Thispolicywrapstheoriginalexceptioninsideanotherexceptionandthrowsthenewexception.

Thefollowingschematicillustratesexamplesofcross-layerandsingle-applicationcomponentexceptionhandling.

Figure1Examplesofexceptionhandlingpolicies

Inthisexample,exceptionsthatoccurinthedataaccesslayerareloggedandthenwrappedinsideanotherexceptionthatprovidesmoremeaningfulinformationtothecallinglayer.Withinthebusinesscomponentlayer,theexceptionsareloggedbeforetheyarepropagated.Anyexceptionsthatoccurinthebusinesscomponentlayerandthatcontainsensitiveinformationarereplacedwithexceptionsthatnolongercontainthisinformation.Thesearesenttotheuserinterface(UI)layeranddisplayedtotheuser.

Forinformationabouthowtodevelopexceptionmanagementstrategies,seeDeterminingAppropriateExceptionPoliciesandActions.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Does the Exception Handling Application Block Do?'%0AEntLib50_fa1a3c57-dbad-4c04-bbb0-5f5b0578ef92%0APlease provide details of the error you have located...%0A


WhenShouldIUsetheExceptionHandlingApplicationBlock?

TheExceptionHandlingApplicationBlockisbestusedinsituationsthatrequireuniformandflexibleproceduresforhandlingexceptions.Forexample,youmightwantconsistentexceptionhandlingproceduresforallcomponentsinaparticulartierofanapplication'sarchitecture.Inaddition,becauseofchangingsecurityorotheroperationalissues,youmightwanttheabilitytochangepoliciesasneeded,withoutrequiringchangestotheapplicationsourcecode.TheExceptionHandlingApplicationBlock,inconjunctionwiththeEnterpriseLibraryconfigurationtools,letsyouaccomplishbothtasks.

Forexample,youcouldusetheconfigurationtoolstodefineapolicythatuseshandlerstoreplaceexceptionsthatcontainsensitiveinformationwithversionsthatdonotincludethatinformation.Theblockthenimplementsthispolicyacrossthecomponentsthatcontaincodethatspecifiesthispolicyshouldbeused.

TheExceptionHandlingApplicationBlockisnotlimitedtocross-tierapplications.Itcanalsobeusedwithinaparticularapplication.Forexample,youcandefinepoliciesthatlogexceptioninformationordisplayexceptioninformationtotheuser.

Ineithercase,policiesareconfiguredwithoutchangingtheapplication'scode.Thismakesthemeasytomaintainorchangewhennewsituationsoccur.Notethat,inallcases,youshouldusetheblocktoperformonlythosetasksthatarespecifictoexceptionhandlingandthatdonotintersectwiththeapplication'sbusinesslogic.Forexample,youcanremovethehandlersthatloganexceptionorwraponeexceptioninanotherwithoutaffectingsuchbasiccapabilitiesasupdatingacustomerdatabase.

ScenariosfortheExceptionHandlingBlock

BenefitsoftheExceptionHandlingApplicationBlock

LimitationsoftheExceptionHandlingApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'When Should I Use the Exception Handling Application Block?'%0AEntLib50_10bbd3de-fcb7-4d37-8eef-e95e962feeb1%0APlease provide details of the error you have located...%0A


DevelopingApplicationsUsingtheExceptionHandlingApplicationBlock

ThistopicdescribeshowtodevelopapplicationsbyusingtheExceptionHandlingApplicationBlock.Itfirstexplainshowtoconfiguretheblockandreferenceitinyourapplications.Next,itdescribeshowtodevelopexception-handlingstrategiesforyourapplications,andexplainshowtousetheblockinspecificscenariossuchasloggingandpropagatingexceptions.Thissectionincludesthefollowingtopics:

EnteringConfigurationInformationAddingApplicationCodeDeterminingAppropriateExceptionPoliciesandActionsSpecifyingDifferentHandlingActionsBasedonExceptionTypeandPolicySendinganExceptiontotheExceptionHandlingApplicationBlockHandlingandThrowingExceptions





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Developing Applications Using the Exception Handling Application Block'%0AEntLib50_a5da2356-d8d2-4418-9add-643b94a0ca0d%0APlease provide details of the error you have located...%0A



TheseproceduresexplainhowtoconfiguretheExceptionHandlingApplicationBlock.Forinformationaboutusingtheconfigurationtools,seeUsingtheConfigurationTools.FordetailsoftheschemafortheExceptionHandlingApplicationBlockconfiguration,seeSourceSchemafortheExceptionHandlingApplicationBlock.Youcanalsoconfiguretheblockincodebyusinganalternateconfigurationsource.Formoreinformation,seeAdvancedConfigurationScenariosandUsingtheFluentConfigurationAPI.

ToaddtheExceptionHandlingApplicationBlock1. Openyourconfigurationfileintheconfigurationeditor.Formore

information,seeConfiguringEnterpriseLibrary.2. OpentheBlocksmenuandthenclickAddExceptionHandling

Settings.3. ThiscreatesanExceptionHandlingSettingssectionwithone

exceptionhandlingpolicythatbydefaultiscalledPolicy,andasingleitemnamedAllExceptionsintheExceptionTypescolumnthatdefinesallexceptionsoftypeSystem.ExceptionorthatinherittheSystem.Exceptionclass.

4. ToeditthepropertiesoftheExceptionHandlingSettingssection,clickthechevronarrowtherightoftheExceptionHandlingSettingsheading.

5. (Optional)Ifyouwanttoencrypttheconfiguration,makeaselectionfromtheProtectionProviderdrop-downlist.YoucanselecttheRsaProtectedConfigurationProviderortheDataProtectedConfigurationProvider.SeeEncryptingConfigurationDataforinformationabouttherestrictionsonusingtheRsaProtectedConfigurationProvider.

6. (Optional)Ifyouwanttorunyourapplicationinpartialtrustmode,changetheRequirePermissionpropertytoFalse.ThedefaultisTrue.

Toconfigureanexceptionhandlingpolicy1. Toaddanexceptionhandlingpolicy,clicktheplussigniconinthe

PoliciescolumnandclickAddPolicy.Thisaddsanewexceptionhandlingpolicyitem.Clicktheexpanderarrowontheleftofthepolicy

headingifthepropertiesarenotvisible.2. (Optional)Renamethepolicy.IntheNametextbox,typetherequired

policyname.3. Toaddanexceptiontypetoapolicy,right-clickthepolicyitemand

clickAddExceptionTypetodisplaythetypeselectordialog.4. Selecttheexceptiontypeinthetypeselectordialogbox.Tofilterthe

list,typethefilterstringintheFiltereditbox.Forexample,type"string"tofilterforallclassescontainingthewordstring.Ifthetypeyouwantisnotlisted,clickAddfromFileorAddfromGAC(fromtheglobalassemblycache)andfindtheassemblycontainingthetypeyouwant,andthenclickOK.ThiscreatesthenewpolicyandadefaultAllExceptionsitem.

5. ClicktheexpanderarrowtotheleftonthenewAllExceptionsnodeintheExceptionTypescolumntodisplaythepropertiesiftheyarenotvisible.

6. SelectthePosthandlingactionyouwant.Thepost-handlingactiondetermineswhatactionwilloccuraftertheexceptionhandlingchaincompletes.Bydefault,thepost-handlingactionissettoNotifyRethrow.Ingeneral,whenyouusetheProcessmethod,youwillconfiguretheexceptionhandlingpolicywithapost-handlingactionofThrowNewExceptionunlessyouwantyourcodetocontinuetoexecuteaftertheblockhandlestheexception.Validvaluesarethefollowing:

NotifyRethrow.Theblockexecutesallhandlersforthisexceptionandreturnstruetotheapplicationatthepointatwhichthepolicywasinvoked.Applicationscheckingthisvaluere-throwtheoriginalexception.However,ifyouusetheProcessmethodyoucannotdetectthevaluereturnedbytheExceptionHandlingApplicationBlock.Internally,theProcessmethodcallstheHandleExceptionmethod,andthrowstheexceptionifthismethodreturnstrue.Therefore,typicallyyourcodewilljustthrowanyexceptionthatisraised.ThrowNewException.Theblockexecutesallhandlersforthisexceptionandthrowstheexceptionthatexistsafterthefinalhandlerruns.However,ifyouusetheoverloadoftheHandleExceptionmethodthattakesanoutparameterthatreturnsthefinalexceptionfromthehandlers,itdoesnot

automaticallythrowtheexception;youmustdothisinyourcode.None.Theblockexecutesallhandlersforthisexceptionandreturnsfalsetotheapplicationatthepointatwhichthepolicymethodwasinvoked.Applicationscheckingthisvalueresumeexecution.

7. Toaddadditionalexceptiontypestothepolicy,repeatsteps3to6.8. Toaddanexceptionhandler,rightclicktheAllExceptionsitemoran

exceptionitemyouadded,pointtoAddHandlers,andthenclicktheexceptionhandlertypethatyouwant:

Replaceexceptionhandler.Thisexceptionhandlerreplacesoneexceptionwithanother.Wrapexceptionhandler.Thisexceptionhandlerwrapstheexceptionthatoccurredwithanotherexception.Loggingexceptionhandler.ThisexceptionhandlerformatsexceptioninformationandusestheLoggingApplicationBlocktologexceptioninformation.TheLoggingApplicationBlockisautomaticallyaddedtotheapplicationconfigurationwhenyouselectalogginghandler.Formoreinformation,seeTheLoggingApplicationBlock.FaultContractexceptionhandler.ThisexceptionhandlerisdesignedforuseatWindowsCommunicationFoundation(WCF)serviceboundaries,andgeneratesanewFaultContractfromtheexception.Customexceptionhandler.Thisoptionallowsyoutoconfigurecustomexceptionhandlers.AcustomhandlerisatypethatimplementstheIExceptionHandlerinterfaceandhasaConfigurationElementTypeofCustomHandlerData.ClickAddfromFileinthetypeselectortoaddacustomhandlerthatislocatedinaseparateassembly.

9. Toaddadditionalexceptionhandlerstothepolicy,repeatstep8.10. Ifrequired,changetheorderoftheexceptionhandlersbyright-clicking

thehandleritemheadingandclickingeitherMoveUporMoveDown.Handlersareexecutedintheorderyouspecify.Typically,youwillplaceaLogginghandlerfirstinthelist,followedbyaWraphandleroraReplaceHandler.

11. Seethefollowingsectionofthistopicfordetailsofhowtoconfigure

exceptionhandlers.

ConfiguringExceptionHandlersToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Entering Configuration Information'%0AEntLib50_fc8160fe-5e08-4174-9744-79a0473edd3f%0APlease provide details of the error you have located...%0A


SourceSchemafortheExceptionHandlingApplicationBlock

ThistopicliststheXMLelementsandattributesusedtoconfiguretheExceptionHandlingApplicationBlock.YoucanmanuallyedittheXMLdata,buttheEnterpriseLibraryConfigurationConsolegreatlysimplifiesthistask.IfyouchoosetomanuallyedittheXML,usetheschemainformationcontainedinthistopic.


<configSections>

<sectionname="exceptionHandling"

type="Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.Configuration.ExceptionHandlingSettings,

Microsoft.Practices.EnterpriseLibrary.ExceptionHandling"/>

</configSections>

Thesection-handlerdeclarationcontainsthenameoftheconfigurationsettingssectionandthenameofthesection-handlerclassthatprocessesconfigurationdatainthatsection.ThenameoftheconfigurationsettingssectionisexceptionHandling.Thenameofthesection-handlerclassisExceptionHandlingSettings.ThisclassisintheMicrosoft.Practices.EnterpriseLibrary.ExceptionHandling.Configurationnamespace.

exceptionHandlingElement

exceptionPoliciesChildElement

exceptionTypesChildElement

exceptionHandlersChildElement




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Source Schema for the Exception Handling Application Block'%0AEntLib50_ddddf570-216e-4e80-90cd-29537d91917a%0APlease provide details of the error you have located...%0A



TheExceptionHandlingApplicationBlockisdesignedtosupportthemostcommonscenariosforhandlingexceptions.Whenyouaddyourapplicationcode,refertothescenariosinKeyScenariosandselecttheonesthatbestsuityoursituation.Usethecodethataccompaniesthescenarioeitherasitisshownhereoradaptitasrequired.

ToprepareyourapplicationtousetheExceptionHandlingApplicationBlock

1. AddareferencetotheExceptionHandlingApplicationBlockassembly.InVisualStudio®,right-clickyourprojectnodeinSolutionExplorer,andthenclickAddReference.ClicktheBrowsetab,selecttheMicrosoft.Practices.EnterpriseLibrary.ExceptionHandling.dllassembly,andthenclickOK.

2. Followingthesameprocedure,setareferencetothefollowingassemblies,


3. IfyouconfigureyourapplicationtousetheLoggingExceptionHandler,setareferencetoMicrosoft.Practices.EnterpriseLibrary.ExceptionHandling.Logging.dllandtherequiredLoggingApplicationBlockassemblies.ForinformationabouttheLoggingApplicationBlockassemblies,seeAddingApplicationCodeinthedocumentationforTheLoggingApplicationBlock.

4. (Optional)TouseelementsfromtheExceptionHandlingApplicationBlockwithoutfullyqualifyingtheelementreference,youcanaddthefollowingusingstatement(C#)orImportsstatement(VisualBasic®)tothetopofyoursourcecodefile.C#

usingMicrosoft.Practices.EnterpriseLibrary.ExceptionHandling;

VisualBasic

ImportsMicrosoft.Practices.EnterpriseLibrary.ExceptionHandling

Note:ForVisualBasicprojects,youcanalsousetheReferencespageoftheProjectDesignertomanagereferencesandimportednamespaces.ToaccesstheReferencespage,selectaprojectnodeinSolutionExplorer,andthenclickPropertiesontheProjectmenu.WhentheProjectDesignerappears,clicktheReferencestab.

Next,addtheapplicationcode.Generally,codethatusestheExceptionHandlingApplicationBlockmustcompletethefollowingsteps:

ObtainaninstanceoftheExceptionManagerclass.Formoredetails,seeCreatingApplicationBlockObjects.Catchanexception.Processanexceptionpolicy.Re-throwtheoriginalexceptionwhereappropriate.

Thefollowingtopicsexplainhowtoincorporatethesestepsintoanapplication:DeterminingAppropriateExceptionPoliciesandActionsSpecifyingDifferentHandlingActionsBasedonExceptionTypeandPolicySendinganExceptiontotheExceptionHandlingApplicationBlockHandlingandThrowingExceptions




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Application Code'%0AEntLib50_870e815f-a445-4281-99d0-af07bef60fee%0APlease provide details of the error you have located...%0A


DeterminingAppropriateExceptionPoliciesandActions

Thisinformationprovidesanoverviewofmanagingexceptionsinyourapplications.Forcompletedesignandimplementationguidelinesforcreatingexceptionmanagementsystemsthatuse.NETtechnologies,seeDesignGuidelinesforExceptionsonMSDN®.

Tobuildsuccessfulandflexibleapplicationsthatcanbemaintainedandsupportedeasily,youmustuseanappropriatestrategyforexceptionmanagement.Youmustdesignyoursystemtomakesurethatitcandothefollowing:

DetectexceptionsLogandreportinformation

Thefollowingtopicsprovideusefuladviceabouthowyoushoulddevelopyourexceptionmanagementstrategies:

GenerateEventsThatCanBeMonitoredExternallytoHelpSystemOperationExceptionHandlingProcessandtheExceptionHandlingApplicationBlockWhentoCatchExceptionsExceptionPropagationHidingExceptionInformationExceptionNotificationPlanningforExceptionHandling


GenerateEventsThatCanBeMonitoredExternallytoHelpSystemOperation

ExceptionHandlingProcessandtheExceptionHandlingApplicationBlock

WhentoCatchExceptions

ExceptionPropagation

HidingExceptionInformation

ExceptionNotification

PlanningforExceptionHandlingToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Determining Appropriate Exception Policies and Actions'%0AEntLib50_9c728a58-1aad-475e-a3ca-85c4618128c4%0APlease provide details of the error you have located...%0A


SpecifyingDifferentHandlingActionsBasedonExceptionTypeandPolicy

TheExceptionHandlingApplicationBlockseparatesthedefinitionofhowanexceptionshouldbeprocessed(whichistheexceptionpolicy)fromtheapplicationcodethatusestheblocktohandleexceptions.Youusetheconfigurationtoolstocreateandnamepolicies.

Byusingexceptionpolicies,theapplicationbehaviorthatoccursinresponsetoanexceptioncanbemodifiedwithoutchangingtheapplicationcode.

ConfiguringExceptionPolicies

ConfiguringExceptionTypes

UnderstandingExceptionHandlersToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Specifying Different Handling Actions Based on Exception Type and Policy'%0AEntLib50_803f1617-63ed-48e1-b9db-8eeb250895ce%0APlease provide details of the error you have located...%0A


SendinganExceptiontotheExceptionHandlingApplicationBlock

InteractionbetweenapplicationcodeandtheExceptionHandlingApplicationBlockoccurswhentheapplicationcodecatchesanexceptionandsendsittotheblocktobehandled.Applicationdevelopersdonothavetoknowhowexceptionswillbehandledbecausetheyhavetospecifyonlythenameoftherelevantexceptionpolicy.

Therearethreemainscenariosinwhichyoumayneedtohandleexceptions.Themostcommonisthefirstofthese,butthistopicexplainshowyoucanusetheblocktoimplementallthreescenarios.Thescenariosare:

HandlingAllExceptionsinaCatchSectionHandlingSpecificExceptionsinaCatchSectionExecutingCodeBeforeorAfterHandlinganException

HandlingAllExceptionsinaCatchSection




HandlingSpecificExceptionsinaCatchSection

ExecutingCodeBeforeorAfterHandlinganExceptionToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Sending an Exception to the Exception Handling Application Block'%0AEntLib50_7e8fb708-d946-49ef-bea5-4a752180fcc3%0APlease provide details of the error you have located...%0A


HandlingandThrowingExceptions

Whenanexceptionoccurs,itpassesupthestackandeachcatchblockcanpotentiallyhandleit.Theorderofcatchstatementsisimportant.Putcatchblocksthattargetspecificexceptionsbeforeageneralcatchblock.Otherwise,thecompilermightissueanerror.Thecommonlanguageruntime(CLR)determinesthepropercatchblockbymatchingthetypeoftheexceptiontothenameoftheexceptionspecifiedinthecatchblock.Ifthereisnospecificcatchblock,ageneralcatchblock,ifitexists,handlestheexception.

DebuggingandExceptionPropagation

HandlingSpecificExceptions

User-FilteredExceptionsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://msdn.microsoft.com/en-us/library/4dy8x9k9(vs.71).aspx

http://msdn.microsoft.com/en-us/library/seyhszts(VS.71).aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Handling and Throwing Exceptions'%0AEntLib50_f7ca52f4-0ebb-4296-bccc-e801dfdb0760%0APlease provide details of the error you have located...%0A


KeyScenarios

Thistopicdescribesthemostcommonsituationsthatdevelopersmustaddresswhenhandlingexceptions.Eachscenarioexplainsthetask,describesareal-worldsituationwheresuchataskmightoccur,andincludescodethatdemonstrateshowtousetheExceptionHandlingApplicationBlocktocompletethetask.Thescenariosarethefollowing:

LogginganException.Thisscenariodemonstrateshowtousethelogginghandlertocollectexceptioninformation,formatit,andsendittotheLoggingApplicationBlock.ReplacinganException.Thisscenariodemonstrateshowtousethereplacehandlertocreateanewexceptionofadefinedtypethatreplacestheoriginalexception.WrappinganException.Thisscenariodemonstrateshowtousethewraphandlertocreateanewexceptionofadefinedtypethatwrapstheoriginalexceptionwithanotherexceptionthatismorerelevant.PropagatinganException.Thisscenariodemonstrateshowtopropagateanexceptioninitsoriginalstateafterrunningachainofexceptionhandlers.DisplayingUser-FriendlyMessages.Thisscenariodemonstrateshowtoeitherreplaceorwrapanexceptionwithonethatprovidessupportorinstructionalinformationfortheuser.NotifyingtheUser.Thisscenariodemonstratesmethodsforlettingauserknowthatanerrorhasoccurred.AssistingSupportStaff.Thisscenariodemonstrateshowsupportstaffcanmatchauser'serrormessagewiththedetailedinformationthatisstoredintheexceptionlog.

Inaddition,thissectioncontainsthetopicShieldingExceptionsatWCFServiceBoundaries,whichdescribeshowunknownexceptionsoccurringinWindowsCommunicationFoundation(WCF)servicesshouldnotbesenttotheclientapplication,inordertopreventdetailsoftheserviceimplementationfromescapingthesecureboundaryoftheservice.

ExceptionsThatOccurDuringExceptionHandlingToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Key Scenarios'%0AEntLib50_d8f141fc-223a-4ec7-8dba-a34f88a39826%0APlease provide details of the error you have located...%0A


LogginganException

Afrequentlyrequiredexception-handlingtaskistologtheinformationassociatedwiththeexception.TheExceptionHandlingApplicationBlock,inconjunctionwiththeLoggingApplicationBlock,letsyoulogformattedexceptioninformationinlocationsspecifiedintheconfigurationfile.Forexample,clientapplicationstypicallylogapplicationinformationintheeventlog,whileaservercomponentofane-commerceapplicationmaylogexceptionsinadatabase.

TypicalGoals

Solution

UsingtheLoggingHandler

ModifyYourApplication




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging an Exception'%0AEntLib50_b5ab286f-434b-4167-82a3-b855de543660%0APlease provide details of the error you have located...%0A


ReplacinganException

Afrequentlyrequiredexception-handlingtaskistoreplacetheoriginalexceptionwithanotherexception.Forexample,ifanexceptionisgoingtocrossatrustboundary,youmaynotwanttosendtheoriginalexceptionbecauseitcontainssensitiveinformation.

TypicalGoals

Solution

UsingtheReplaceHandler




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Replacing an Exception'%0AEntLib50_4ddebf5c-9118-4486-9ae2-6f43a4a35753%0APlease provide details of the error you have located...%0A


WrappinganException

Afrequentlyrequiredexception-handlingtaskiswrappingoneexceptionwithadifferentexception.WrappinganexceptioncreatesanewexceptionofadefinedtypeandsetstheoriginalexceptionastheInnerExceptionobjectofthenewexception.Usethewrappingcapabilityinsituationswheretheoriginalexceptiontypemustbemappedtoanewexceptiontypeforusebyothertierswithinthearchitectureoftheapplication.Youcanencapsulateandinterpretdetailsoftheunderlyinglayer'soriginalexceptionwithoutlosinganydetailsaboutthatexception.Youcanwraptheoriginalexceptioneitherinanexistingexceptiontypeorinacustomexceptiontypethatyoucreate.Thefollowingexplainsasituationwhenyouwouldwanttowrapanexception:

1. AbusinessservicenamedUpdateCustomercallsadatalayerservice.2. Thedatalayerservicefailsandthrowsanexception.Thiscouldbeany

oneofmanyexceptionsthatindicatethattheupdatefailed.Somesetsoftheseexceptionsindicatethatrecoverymaybepossiblewitharetry(forexample,ifarecordislocked)whileothersarenon-recoverable(forexample,ifthereisaconcurrencyviolationoradirtyrecord).

3. Theexceptionhandlermapsandwrapsthesesetsofexceptionsintotwocustomexceptiontypes,RecoverableUpdateExceptionandFatalUpdateException.

4. Thebusinessservicehandlestheexceptionbasedonthewrappingtypeandtakestheappropriateaction,eventhoughitisinsulatedfromdetailedknowledgeoftheunderlyingfailure.

TypicalGoals

Solution

UsingtheWrapHandler




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Wrapping an Exception'%0AEntLib50_dcf08174-cbdf-4f81-96ce-24400bc19b79%0APlease provide details of the error you have located...%0A


PropagatinganException

Afrequentlyrequiredexception-handlingtaskistoallowtheoriginalexceptiontopropagateupthecallstackunchanged.Youmaywanttodothisbecausethehandlersonlyperformactionssuchasloggingthatleavetheexceptionunchangedorbecauseotheractions,suchaswrappingandreplacing,havebeenturnedoff.Forexample,aroutinewithinabusinesslogiccomponentmaylogexceptionsatthepointwheretheyaredetected.Itthenpropagatesthatexceptiontothecallerforadditionalhandling.

TypicalGoals

Solution

PropagatinganException




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Propagating an Exception'%0AEntLib50_2e805c79-f4ad-4526-9dbd-74eee6d20349%0APlease provide details of the error you have located...%0A


DisplayingUser-FriendlyMessages

Youmaywanttoreplacethemessageintheoriginalexceptionwithamoreappropriate,user-friendlymessage.Todothis,youmustreplacetheoriginalexceptionwithanotherexceptionthathasamoreappropriatemessageassociatedwithit.Forexample,exceptionsthatoccurinthedataaccesslayerofanapplicationcanbereplacedwithanexceptionoftypeSystem.ApplicationException.Thisusesthemessage,"Theapplicationisunabletoprocessyourrequestatthistime."Thismessageisthendisplayedtotheuser.

TypicalGoals

Solution

DisplayingUser-FriendlyMessagesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Displaying User-Friendly Messages'%0AEntLib50_4aef5812-d607-47c9-901f-65ae58367261%0APlease provide details of the error you have located...%0A


NotifyingtheUser

WhenyouusetheExceptionHandlingApplicationBlock,afrequentlyrequiredtaskistonotifytheuserwhenanexceptionoccurs.(Generally,thisshouldbecompletedafterthemessagehasbeenchangedtoonethatissuitablefortheparticularuser.Formoreinformation,seeDisplayingUser-FriendlyMessages.)Dependingontheapplicationtype,youcandothisusingaWindowsFormsdialogboxoraWebpage.Whenanexceptioncannotbehandledwithintheapplication,theusermustreceiveanotificationthatanerroroccurred,alongwithsomeguidanceofwhatheorsheshoulddonext.

TypicalGoals

Solution

NotifyingtheUser




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Notifying the User'%0AEntLib50_94d9d4bf-4cb3-4912-9e29-60f0a713ab13%0APlease provide details of the error you have located...%0A


AssistingSupportStaff

WhenyouusetheExceptionHandlingApplicationBlock,afrequentlyrequiredtaskistoallowsupportstafftoaccessdetailedinformationtoassistuserswhenexceptionsoccur.Whenanexceptionoccursthatcannotbehandled,usersaregenerallyshownafriendlyerrormessage.Usersmayhavetocallsupportstaff,andsupportstaffmayneedmorethantheusererrormessagetodeterminewhatwentwrongandhowtofixtheproblem.Thisscenariodemonstrateshowtomatchtheuser'serrormessagewiththedetailedexceptionlogthatcanbeaccessedbysupportstaff.

TypicalGoals

Solution

AssistingSupportStaff




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Assisting Support Staff'%0AEntLib50_b590664e-bdb0-4c5f-b844-0d7a90da2bc7%0APlease provide details of the error you have located...%0A


ShieldingExceptionsatWCFServiceBoundaries

InWindowsCommunicationFoundation(WCF),topreventdetailsoftheserviceimplementationfromescapingthesecureboundaryoftheservice,unknownexceptionsshouldnotbesenttotheclientapplication.ThisiscontrolledthroughtheincludeExceptionDetailInFaultsattributeinthe<serviceDebug>elementintheWCFconfiguration.Toenableexceptionshielding,thisattributemustbesettofalse.Ifnotspecifiedintheconfigurationfile,thispropertyissettofalse.

Note:TheincludeExceptionDetailInFaultsconfigurationsettingisusedonlyforunknownorunhandledexceptions.Itdoesnothaveanyeffectonknownexceptions,wheretheoperationhasaFaultContractwiththeknownfaulttypeandtheoperationthrowsaFaultException<knownFault>whereknownFaultisinthefaultcontract.

ExceptionshieldinghelpspreventaWebservicefromdisclosinginformationabouttheinternalimplementationoftheservicewhenanexceptionoccurs.Thefollowingforcesexplainwhyyoushoulduseexceptionshielding:

Exceptiondetailsmaycontaincluesthatanattackercanusetoexploitresourcesusedbythesystem.Informationrelatedtoanticipatedexceptionsneedstobereturnedtotheclientapplication.ExceptionsthatoccurwithinaWebserviceshouldbeloggedtosupporttroubleshooting.

Onlyexceptionsthathavebeensanitizedoraresafebydesignshouldbereturnedtotheclientapplication.Exceptionsthataresafebydesigndonotcontainsensitiveinformationintheexceptionmessageandtheydonotcontainadetailedstacktrace,eitherofwhichmightrevealsensitiveinformationabouttheWebservice'sinnerworkings.YoushouldusetheExceptionShieldingpatterntosanitizeunsafeexceptionsbyreplacingthemwithexceptionsthataresafebydesign.

TheExceptionHandlingApplicationBlockincludessupportforexceptionshieldingatWCFserviceboundaries.Thissupportconsistsofthefollowing:

TheExceptionShieldingAttribute,whichisusedtoassociateanamedexceptionhandingpolicyconfiguredintheExceptionHandlingApplicationBlockwithaWCFserviceoperation.Formoreinformation,seethefollowingsectionUsingtheExceptionShieldingAttribute.TheFaultContractExceptionHandler,whichconvertsanexceptiontoaspecifictypeofFaultContractandmapsthedesiredpropertiesoftheexceptiontotheFaultContract.Formoreinformation,seethefollowingsectionUsingtheFaultContractExceptionHandler.

UsingtheExceptionShieldingAttribute

UsingtheFaultContractExceptionHandlerToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Shielding Exceptions at WCF Service Boundaries'%0AEntLib50_14609680-60a5-48c0-b457-50a079d0a7dc%0APlease provide details of the error you have located...%0A


DesignoftheExceptionHandlingApplicationBlock

TheExceptionHandlingApplicationBlockisdesignedtoachievethefollowinggoals:

Encapsulatethelogicusedtoperformthemostcommonexceptionhandlingtasksintominimalapplicationcode.Relievedevelopersoftherequirementtowriteduplicatecodeandcustomcodeforcommonexceptionhandlingtasks.Allowexceptionhandlingpoliciestobechangedaftertheyhavebeendeployedandtoensurethatchangeshappensimultaneouslyandconsistently.Incorporatebestpracticesforexceptionhandling,asdescribedintheDesignGuidelinesforExceptions.





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Exception Handling Application Block'%0AEntLib50_2f60b9fa-0c81-4866-bc77-800db87c26a5%0APlease provide details of the error you have located...%0A


DesigningforSimplifiedCatchBlocks

Commonexceptionhandlingbehavior,suchasloggingandreplacingexceptionstohidesensitiveinformation,typicallyrequiresmultiplelinesofcode.Updatingexception-handlingbehaviortoaccommodateachangeinanexceptionhandlingpolicyusuallyinvolvesupdatingmultiplefilesandlinesofcode.Thisprocesscanbeerror-prone,anditisdifficulttoensurethatpoliciesareupdatedconsistentlyacrossalllayersofanapplication.

TheExceptionHandlingApplicationBlocksimplifiesboththeexceptionhandlingcodeandtheprocessofupdatingthatcode.Itdoesthisbyassociatingexception-handlingbehaviorwithpolicynamessuchasDataAccessLayerPolicyandTrustBoundaryPolicy.Thebehaviorsrepresentedbypolicynamesarecontrolledexternally,intheconfigurationfortheapplication.Thismeansthatadeveloperneedstouseonlytwoelementstowritecodeinthecatchblockofanapplication:

AcalltotheHandleExceptionorProcessmethodthatpassesthepolicynameandtheexception.AcheckofthereturncodefromtheHandleExceptionmethod;ifitreturnstrue,theoriginalexceptionshouldbere-thrown.

DesignImplications

APISupportforPolicyNamesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Designing for Simplified Catch Blocks'%0AEntLib50_7fe3b885-e438-4293-add1-4281faf53765%0APlease provide details of the error you have located...%0A


DesigningforEncapsulationofBehaviorinReusableHandlers

TheExceptionHandlingApplicationBlockhelpsdeveloperstocreateexceptionhandlersthatrepresentcommonexceptionhandlingtasks.Thesehandlers,aswellascombinationsofhandlers,canbeusedbydifferentpolicies.

DesignImplications




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Designing for Encapsulation of Behavior in Reusable Handlers'%0AEntLib50_84690cf3-bbf8-428c-8b61-7e209bc39445%0APlease provide details of the error you have located...%0A


ExtendingandModifyingtheExceptionHandlingApplicationBlock

Initsoriginalstate,theExceptionHandlingApplicationBlockworkswellfortypicalexceptionhandlingscenarios,suchaslogginganexceptionmessage,wrappingoneexceptionwithanother,orreplacinganexceptionwithadifferentexception.However,theremaybetimeswhenyouhavetocustomizecertainbehaviorsoftheblocktobettersuityourapplication'sparticularrequirements.Therearetwowaystodothis.YoucanextendtheExceptionHandlingApplicationBlockusingthebuilt-inextensionpoints.Inaddition,youmaychoosemodifytheblockbymakingchangestoitssourcecode.

YouextendtheExceptionHandlingApplicationBlockthroughdesignatedextensionpoints.Typically,thesearecustomclasseswrittenbyyouthatimplementaparticularinterfaceorderivefromanabstractclass.Becausethesecustomclassesexistinyourapplicationspace,youdonothavetomodifyorrebuildtheExceptionHandlingApplicationBlock;instead,youcandesignateyourextensionsthroughconfigurationsettings.

Youcanextendtheblockbyaddinganewtypeofexceptionhandlerorexceptionformatter.Thefollowingtableliststheinterfacesandbaseclassesthatyoucanusetoextendtheblock.


ExceptionHandler IExceptionHandler

ExceptionFormatter ExceptionFormatter

FormoredetailsofhowtoextendandmodifytheblockandEnterpriseLibrary,seethefollowingtopics:

AddingaNewExceptionHandlerAddingaNewExceptionFormatterCreatingCustomProvidersforEnterpriseLibraryExtendingandModifyingEnterpriseLibrary

Toprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.


Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying the Exception Handling Application Block'%0AEntLib50_2d5e95ff-3097-4083-96b8-0cf869196c04%0APlease provide details of the error you have located...%0A


AddingaNewExceptionHandler

Toaddanewexceptionhandler,youmustfirstcreateanewclassthatimplementstheIExceptionHandlerinterface.Afteryoucompilethenewclassintoanassembly,youcanusetheEnterpriseLibraryConfigurationConsoletoaddittotheExceptionHandlingApplicationBlockconfigurationforyourapplication.

CreatingaNewExceptionHandlerClassToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding a New Exception Handler'%0AEntLib50_eb044f0e-a7b5-4645-9119-750f016138ec%0APlease provide details of the error you have located...%0A


AddingaNewExceptionFormatter

Toaddanewexceptionformatter,youmustcreateanewexceptionclassthatderivesfromtheExceptionFormatterclass.YournewclasscanderivedirectlyfromExceptionFormatterorfromoneoftheexceptionformattersthatshipwiththeExceptionHandlingApplicationBlock.TheblockincludestheclassesTextExceptionFormatterandXmlExceptionFormatter,bothofwhichderivefromtheExceptionFormatterclass.

ExceptionformattersmustincludethehandlinginstanceID,HandlingInstanceId.ThehandlinginstanceIDvalueisgeneratedoneachexceptionhandlingrequest.EachindividualexceptionformatterhandlesthehandlinginstanceIDasappropriateforthatformatter.TheXmlExceptionFormatteraddsitasanattributeofthetop-levelExceptionelement,whiletheTextFormatteraddsitasthefirstlineoftext.AHandlingInstanceIdequaltoGuid.Emptycanbeignored.

TheloggingexceptionhandlerdoesnotaddtheexceptionhandlingIDtothemessagetolog.TheformatterhandlestheID.ExceptionFormattertypesusedwiththeLoggingexceptionhandlermustimplementaconstructorwithparametersoftypeTextWriter,Exception,andGuid,asshowninthefollowingcode.C#

publicMyExceptionFormatter(TextWriterwriter,Exceptionex,GuidhandlingInstanceId)

:base(ex,handlingInstanceId)

{

...

}

VisualBasic

PublicSubNew(writerAsTextWriter,exAsException,handlingInstanceIdAsGuid)

MyBase.New(ex,handlingInstanceId)

...

EndSub

Note:IfyouhavecustomformattersdesignedforusewithversionsofEnterpriseLibrarypriortoversion4.1,youmustupdatethemsothatthehandlinginstanceIDisnotlost.

CreatingaNewExceptionFormatterClassToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding a New Exception Formatter'%0AEntLib50_4ab95d05-9102-469a-bfc7-199bc043dac1%0APlease provide details of the error you have located...%0A



Twoofanadministrator'smaintaskswillbetomakesurethattheinitialdeploymentoftheExceptionHandlingApplicationBlockisplannedandmanagedandtomakesurethatsubsequentupdatesaredeployedwithminimalimpacttoexistingapplicationsthatusetheblock.FordetailsofdeployingandupdatingEnterpriseLibraryandtheblocks,seeDeployingEnterpriseLibrary.

Inaddition,administratorsmustdecideiftheywishtousetheinstrumentationexposedbytheblock.Fordetailsofhowtoenableanddisableinstrumentation,seeEnablingInstrumentation.ForinformationabouttheinstrumentationcontainedwithintheExceptionHandlingApplicationBlock,seethefollowingtopics:

ExceptionHandlingApplicationBlockPerformanceCountersExceptionHandlingApplicationBlockEventLogEntries




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deployment and Operations'%0AEntLib50_4b287cf0-c1ae-48b8-b1ea-b5a885ced512%0APlease provide details of the error you have located...%0A


ExceptionHandlingApplicationBlockPerformanceCounters

ThefollowingtabledescribestheExceptionHandlingApplicationBlockperformancecounters.


Description

ExceptionHandlersExecuted/sec

Therateatwhichexceptionhandlerswereexecuted.

ExceptionsHandled/sec Therateatwhichexceptionswerehandled.

TotalExceptionsHandled Thetotalnumberofexceptionshandled.

TotalExceptionsHandlersExecuted

Thetotalnumberofexceptionhandlersthatwereexecuted.

Aratecountersamplesanincreasingcountofeventsovertimeanddividesthevaluesbythechangeintimetodisplayarateofactivity.Formoreinformationaboutperformancecounters,seeOverviewofPerformanceMonitoringinthe.NETFrameworkClassLibrary.





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Exception Handling Application Block Performance Counters'%0AEntLib50_162590e1-4469-4ae7-b442-9986c6d186c2%0APlease provide details of the error you have located...%0A


ExceptionHandlingApplicationBlockEventLogEntries

TheExceptionHandlingApplicationBlockisinstrumentedtologentriestotheapplicationeventlogforavarietyofevents.ThistopicliststheExceptionHandlingApplicationBlockeventlogentries.Thelisteneristheclassthatraisedtheevent.

ExceptionHandlingErrorEvent

ConfigurationErrorEvent

InternalErrorEventToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Exception Handling Application Block Event Log Entries'%0AEntLib50_ea0fe392-4802-405a-af57-f78d9328efdf%0APlease provide details of the error you have located...%0A


TheLoggingApplicationBlock

Developersfrequentlywriteapplicationsthatrequireloggingfunctionality.Typically,theseapplicationsformatandloginformationinresponsetoapplicationevents.Forexample,theymayberequiredtologinformationinresponsetounexpectedconditions,suchasanapplicationexception,orfailuretoconnecttoadatabase.Developersalsowritecodetotraceapplicationflowthroughcomponentsduringtheexecutionofanapplicationusecaseorscenario.Inaddition,applicationsoftenneedtowriteinformationlocallyandoveranetwork.Insomecases,youmayneedtocollateeventsfrommultiplesourcesintoasinglelocation.

TheEnterpriseLibraryLoggingApplicationBlocksimplifiestheimplementationofcommonloggingfunctions.YoucanusetheLoggingApplicationBlocktowriteinformationtoavarietyoflocations:

TheeventlogAne-mailmessageAdatabaseAmessagequeueAtextfileAWindows®ManagementInstrumentation(WMI)eventCustomlocationsusingapplicationblockextensionpoints

ThissectionincludesthefollowingtopicsthatwillhelpyoutounderstandandusetheLoggingApplicationBlock:

WhatDoestheLoggingBlockDo?Thistopicprovidesabriefoverviewthatwillhelpyoutounderstandwhattheblockcando,andexplainssomeoftheconceptsandfeaturesitincorporates.Italsoprovidesasimpleexampleofhowtowritecodetousetheblock.WhenShouldIUsetheLoggingBlock?Thistopicwillhelpyoutodecideiftheblockissuitableforyourrequirements.Itexplainsthebenefitsofusingtheblock,andanyalternativetechniquesyoumayconsider.Italsoprovidesdetailsofanylimitationsoftheblockthatmayaffectyourdecisiontouseit.DevelopingApplicationsUsingtheLoggingApplicationBlock.ThistopicexplainshowtousetheLoggingApplicationBlockinyour

applications.Itshowshowtoconfiguretheapplicationblocktoperformcommontasksandhowtoaddapplicationcodetotheapplicationblockwhererequired.KeyScenarios.Thistopicdemonstrateshowtousetheapplicationblocktoperformthemostcommonloggingoperations.DesignoftheLoggingApplicationBlock.Thistopicexplainsthedecisionsthatwentintodesigningtheapplicationblockandtherationalebehindthosedecisions.ExtendingandModifyingtheLoggingApplicationBlock.Thistopicexplainshowtoextendtheapplicationblockbycreatingyourowncustomtracelisteners,logformatters,andlogfilters;andexplainshowtomodifythesourcecode.DeploymentandOperations.Thistopicexplainshowtodeployandupdatetheapplicationblock'sassembliesandalsocontainsinformationabouttheinstrumentationintheblock.

MoreInformationFormoreinformationaboutloggingandmanagingothercrosscuttingconcerns,seethefollowingpatterns&practicesguides:

MicrosoftApplicationArchitectureGuide,2ndEditionDesignGuidelinesforExceptions






mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Logging Application Block'%0AEntLib50_318c9d2f-1ff6-438b-8d74-0b17074f470d%0APlease provide details of the error you have located...%0A


WhatDoestheLoggingBlockDo?

Althoughtheprocessofcreatingandwritinglogentriesisrelativelysimple,thenumberofoptionsavailable(suchasthemanyloggingtargetsandtheabilitytofilterentries)meansthattheunderlyingstructureoftheblockandtheoptionsavailableforusingitcanseemcomplex.Thefollowingschematicshowshowthemaintypesofobjectintheblockworktogethertoprovideflexibilitywhencreatingandwritinglogentries.

Thefivemaintypesofobjectsare:LogWriter.Thelogwriteristhemainentrypointforcreatinglogentriesandwritingthemtoyourchosenloggingtargets.Itcreatesaninstanceofalogentrycontainingtheinformationtobelogged,andinteractswiththeotherobjectsthatfilterthelogentry,assignittooneormorecategories,formatit,anddispatchittotheappropriatetargets.LogFilters.Logfilterscanblockorallowalogentrybasedonanumberoffeatures.Eachlogentryisassignedtooneormorecategories(thedefaultistheGeneralcategory),andthecategorylogfiltercanusethesecategoriestopassorblockalogentry.Inaddition,twospeciallogfilterscanblockalllogging,orblocklogentrieswithaprioritylowerthanaspecifiedvalue.Youdefinethecategories,priorities,andthesettingsforthelogfiltersintheconfigurationfortheblock.TraceSources.Tracesourcesareeffectivelyasetofbucketsintowhichtheblockplacesalllogentriesthathavenotbeenblockedbyalogfilter.Youusethesebucketstodefinewherelogentrieswillbedispatchedto—youcanthinkofthemasbeingthesourceofthelogentriesthatwillactuallybedispatchedtothetargetdestinations.Therearetwobasictypesoftracesources:

Thereisatracesourceforeachcategoryyoudefineintheconfigurationoftheblock.ThesearecalledCategorySources.Therearethreebuilt-intracesources:onethatreceivesalllogentries,onethatreceiveslogentrieswhenanerroroccursduringprocessingordispatchingofthelogentry,andonethatreceivesalllogentriesthatdonotmatchanyconfiguredcategory.ThesearecalledSpecialSources.

TraceListeners.Tracelistenersrepresentthetargetsforyourlogentries,andyouconfigureoneforeachtypeoftarget(suchastheWindows®EventLog,adiskfile,andane-mailmessage)towhichyouwanttosendthelogentries.Tracelistenerslistenforlogentriesarrivinginthetracesourcebuckets,formateachlogentryasrequired,anddispatchittothetargetconfiguredforthattracesource.Yourconfigurationmapseachtracesource(eachcategorysourceyoudefineplusthethreespecialsources)tooneormoretracelisteners.Theimportantpointtonotehereisthatthisallowsyoutodispatcheachlog

entrytozero,one,ormoretargets(suchassendingitase-mailaswellaswritingittotheWindowsEventLog).LogFormatters.Eachtracelisteneryouaddtoyourconfigurationcanusealogformattertoconvertthedatainthelogentryfromaseriesofpropertiesintoformatsuitableforsendingtothelogtarget.Theblockcontainsatextformatterthatyoucanconfigurewithtracelistenersthatdispatchlogentriestotargetssuchasdiskfiles,e-mail,orWindowsEventLog;andabinaryformatterthatserializesthelogentrydataintoaformatsuitablefortransmissiontotargetssuchasWindowsMessageQueuing(MSMQ).Thetextformatterisconfigurablesothatyoucanmodifytheformatandcontentofthetextmessage,includingusingplaceholdersforthevaluesofthepropertiesofthelogentry.

TheLoggingProcessSequence




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Does the Logging Block Do?'%0AEntLib50_75d79ffd-f3cf-48e7-bcbe-03acedf87ac0%0APlease provide details of the error you have located...%0A


WhenShouldIUsetheLoggingBlock?

IfyourapplicationshavearequirementtologinformationtoWindowsEventLog,e-mail,adatabase,amessagequeue,WindowsManagementInstrumentation(WMI),orafile,youshouldconsiderusingtheLoggingApplicationBlocktoprovidethisfunctionality.Inparticular,theLoggingApplicationBlockisusefulifyouneedtofilterloggingmessagesbasedoncategoryorpriority,ifyouneedtoformatthemessages,orifyouneedtochangethedestinationofthemessagewithoutchangingtheapplicationcode.TheLoggingApplicationBlockisalsodesignedtobeextensibleandincludesthefacilitytocreatecustomformattersandtracelisteners,whichyoucanadapttomeetyourapplication'sloggingrequirements.

ScenariosfortheLoggingApplicationBlock

BenefitsoftheLoggingApplicationBlock

LimitationsoftheLoggingApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'When Should I Use the Logging Block?'%0AEntLib50_96dff44d-fb3e-4c3d-b6e4-948d0f8ac4f1%0APlease provide details of the error you have located...%0A


DevelopingApplicationsUsingtheLoggingApplicationBlock

ThistopicdescribeshowtodevelopapplicationsusingtheLoggingApplicationBlock.Itexplainshowtoconfiguretheapplicationblocktoperformparticulartasksandhowtousetheapplicationblockaccordingtoparticularapplicationscenariossuchaspopulatingandraisingeventsfromcode.Itincludesthefollowingtopics:

EnteringConfigurationInformationUsingtheDistributorServiceAddingApplicationCode

Ifyouwanttodeliverlogentriesatacentrallocationforprocessing,youcanusetheLoggingApplicationBlockwithMessageQueuing(alsoknownasMSMQ)toallowyoutodothis.Byconfiguringmultipleapplicationstousethesamemessagequeue,youcandeliverallthelogentriestooneplace.FordetailsofhowtoinstallandconfiguretheLoggingApplicationBlockinthisscenario,seeUsingtheDistributorService.

IfyouareusingtheLoggingApplicationBlockwithaWindowsCommunicationFoundation(WCF)application,youmustconfigureintegrationwithWCF.Fordetails,seeConfiguringWCFIntegrationTraceListeners.


Thistopicassumesyouareusingtheapplicationblockinitsoriginalstate,withoutextendingit.(Tolearnhowtoaddfunctionality,seeExtendingandModifyingtheLoggingApplicationBlock.)




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Developing Applications Using the Logging Application Block'%0AEntLib50_af68990c-87d7-4af5-bdb8-ad1f3d611075%0APlease provide details of the error you have located...%0A



ThissectionexplainshowtoconfiguretheLoggingApplicationBlock.Foranoverviewandexampleofconfiguringtheblock,seeConfigurationOverview.FordetailsoftheschemafortheLoggingApplicationBlockconfiguration,seeSourceSchemafortheLoggingApplicationBlock.Youcanalsoconfiguretheblockincodebyusinganalternateconfigurationsource.Formoreinformation,seeAdvancedConfigurationScenariosandUsingtheFluentConfigurationAPI.

Note:RuntimechangestotheconfigurationoftheLoggingApplicationBlockareautomaticallydetectedafterashortperiod,andtheloggingstackisupdated.However,youcannotmodifytheloggingstackatruntimethroughcode.Fordetailsofusingconfigurationmechanismsthatyoucanupdateatruntime,seeUpdatingConfigurationSettingsatRunTime.

ToaddtheLoggingApplicationBlock1. Opentheconfigurationfile.Formoreinformation,seeConfiguring

EnterpriseLibrary.2. OpentheBlocksmenuandthenclickAddLoggingSettings.3. Thisaddsadefaultgeneralcategory,thethreestandardspecial

categories,adefaulteventloglistener,andadefaulttextformattertotheconfiguration.

4. ClickthechevronexpanderarrowintheLoggingSettingssectiontoviewallsettingsforthissection.

5. Clicktheexpanderarrowattheleftofthegeneralcategory,thespecialcategories,theeventloglistener,orthetextformattertoviewandsettheirpropertiesasdescribedinthefollowingtopics.

AfteryouaddtheLoggingApplicationBlocktotheapplicationconfiguration,youcanconfiguresomeorallofthefollowingfeatures.Youshouldperformthesetasksinthefollowingorder:

ConfiguringTraceListenersConfiguringFormatters

ConfiguringTraceSourceCategoriesConfiguringLoggingFiltersConfiguringtheApplicationBlock




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Entering Configuration Information'%0AEntLib50_0d425989-6830-4e25-9fcf-e4dc2db4501a%0APlease provide details of the error you have located...%0A


ConfigurationOverview

TounderstandhowyouconfigureandusetheLoggingApplicationBlock,youmustbefamiliarwiththewaytheblockprocesseslogentries.ThetopicWhatDoestheLoggingBlockDo?providesasimplifiedoverviewoftheprocessandwillhelpyouwhenyoucometoconfiguretheblock.

ThefollowingstepsillustratethegeneralprocessforconfiguringtheLoggingApplicationBlock.ItassumesyouwanttousetwocategoriesnamedDevandOperations.

1. AddthetracelistenersyouwanttousetooutputthelogginginformationbyclickingontheplussigniconintheLoggingTargetListenerssectionoftheLoggingSettingsconfigurationpaneandclickingAddLoggingTargetListenerstodisplaythelistoflisteners.Whenyouselectalistener,itisaddedtotheLoggingTargetListenerssectionwhereyoucanthensetitsproperties.

2. AddtheformattersyouwantthetracelistenerstousetoformattheoutputbyclickingontheplussigniconintheLogMessageFormatterssectionoftheLoggingSettingsconfigurationpaneandclickingAddLogMessageFormatterstodisplaythelistofformatters.Whenyouselectaformatter,itisaddedtotheLogMessageFormatterssectionwhereyoucanthensetitsproperties.

3. SettheFormatterNamepropertyofeachtracelistenerintheLoggingTargetListenerssectionoftheLoggingSettingsconfigurationpanetospecifytheappropriateformatter.

4. AddthecategoryfiltersyouwanttousetotheCategoriessectionoftheLoggingSettingsconfigurationpanebyclickingontheplussigniconintheCategoriessectionoftheLoggingSettingsconfigurationpaneandclickingAddCategory.AnewcategoryitemisaddedtotheCategoriessectionwhereyoucanthensetitsproperties.Clickonitspropertyexpanderarrowifthepropertiesarenotvisible.

5. AddareferencetoeachofthetracelistenersyouwanttousetooutputthelogginginformationtoeachofthecategoriesyoucreatedintheCategoriessectionoftheLoggingSettingsconfigurationbyclickingtheListenerspropertyplussigniconandselectingaconfiguredloggingtargetlistener.EachentryhereisareferencetooneofthetracelistenersyoupreviouslyconfiguredintheTraceListenerssection.Youcanaddmorethanonetracelistenerreferencetoeachcategoryfilteryoucreate.Forexample,youcouldspecifythefollowing:

AlogentrycontainingthecategorynameDevwillgotoaneventlogtracelistener(sothatitappearsinWindowsEventLog)AlogentrycontainingthecategorynameOperationswillgotoane-mailtracelistenerandtoanXMLtracelistener.

6. AddareferencetoeachofthetracelistenersyouwanttousetooutputthelogginginformationtotheappropriatesubsectionsoftheSpecialCategoriessectionoftheLoggingSettingsconfigurationpane.Forexample,youmaywanttodothefollowing:

Sendthelogentrytoane-mailtracelistenerwhenanerroroccurswithintheloggingsystembyaddingareferencetothistracelistenertotheLoggingErrors&Warningssection.Sendthelogentrytoaneventlogtracelistenerwhenthelogentrydoesnotmatchanyconfiguredcategorybyaddinga

referencetothistracelistenertotheUnprocessedCategorysection.Sendalllogentries,irrespectiveofcategoryorcontent,toaFlatFiletracelistenerbyaddingareferencetothistracelistenertotheAllEventssection.

7. Settheremainingpropertiesforeachcategoryorspecialfilter.Specifythelogginglevel,suchasCritical,Error,Warning,orAll,bysettingtheMinimumSeveritypropertyforeachcategoryfilter.

8. Finally,addanylogfiltersyouwanttousetotheLoggingFilterssectionoftheLoggingSettingsconfigurationpanebyclickingontheplussigniconintheLoggingFilterssectionoftheLoggingSettingsconfigurationpaneandclickingAddLoggingFilters.ThefiltertypeyouselectisaddedtotheLoggingFilterssectionwhereyoucanthensetitsproperties.Clickonitspropertyexpanderarrowifthepropertiesarenotvisible.Forexample,youcoulduseacategoryfiltertoblockallloggingoperationsexceptthosethatspecifyoneofthetwocategoriesnamedDevorOperations.

ForspecificdetailsofhowtoconfigureeachsectionoftheLoggingApplicationBlockconfiguration,seeEnteringConfigurationInformation.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuration Overview'%0AEntLib50_3a6ba613-78b1-4b24-b226-55e368e41554%0APlease provide details of the error you have located...%0A


ConfiguringTraceListeners

Tracelistenersreceivelogentriesandwritethemtotheappropriatedestinations.ThefollowingproceduredescribeshowtoconfigurethetracelistenerssuppliedwithEnterpriseLibraryandcustomtracelistenersthatyoucreate.ThereisalsoaspecificprocedureforconfiguringthetwotracelistenersthatarerequiredforintegrationwithWCF.Formoredetailsofthisprocedure,seeConfiguringWCFIntegrationTraceListeners.

Note:Tracelistenerlogshavevulnerabilitiesandshouldbeprotectedasappropriate,dependingonwhetherthetracelistenerwriteslogentriestoafile,databaseorMSMQmessagequeue.

Fortracelistenersthatwritelogentriestofilesyoushouldprotectthelogsbyusingaccesscontrollists.ThisincludesFlatFile,Rollingflatfile,WMIandXMLtracelistenerlogs.

Fortracelistenersthatwritelogentriestodatabasesyoushouldprotectaccesstologsbyusingusernamesandpasswords.Thisincludesthedatabasetracelistener.

FortracelistenersthatwritelogentriestoMSMQmessagequeuesyoushouldallowonlyauthorizeduserstoreadinformationfromMSMQ.ProtectthequeuewithrelevantaccesscontrollistsandfollowanysecurityconsiderationsspecifictoMSMQ.Thisincludesthemessagequeuingtracelistener.

ConfiguringtheBuilt-inTraceListeners

ConfiguringCustomTraceListenersToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring Trace Listeners'%0AEntLib50_a0ea0d8b-7675-48b8-9b5f-9d6d8e2382f0%0APlease provide details of the error you have located...%0A


TraceListenerProperties

Thesetablesexplainthepropertiesforthedifferenttracelisteners.Therearetablesforthefollowingtracelisteners:

DatabaseTraceListener.Thistracelistenerwritesformattedlogentriestoadatabase.E-mailTraceListener.Thistracelistenersendslogentriesase-mailmessages.EventLogTraceListener.ThistracelistenerformatslogentriesandwritesthemtoWindowsEventLog.FlatFileTraceListener.Thistracelistenerwriteslogentriestoatextfile.MessageQueuingTraceListener.Thistracelistenerwriteslogentriestoamessagequeue.RollingFlatFileTraceListener.Thistracelistenercreatesanewlogfiledependingonthecurrentlogfileageand/orsize.SystemDiagnosticsTraceListener.Thisisoneofthe.NETFrameworktracelistenerssuchastheConsoleTraceListener.WMITraceListener.ThistracelistenerraisesaWMImanagementeventforeachlogentryreceived.XMLTraceListener.ThistracelistenerisusedtooutputlogmessagestoanXMLformattedfile.

DatabaseTraceListenerThefollowingtableliststhepropertiesthatyoucansetwhenyouaddaDatabaseTraceListener.

Property Description

AddCategoryProcedure

Thenameofthestoredprocedurethataddsacategory.ThedefaultisAddCategory.Thisisrequired.

DatabaseInstance

ThenameofthedatabaseinstancetouseasconfiguredintheDataSettingssectionoftheconfiguration.Thisisrequired.

SeverityFilter

Appliesafilterthatselectsthelevelofmessagethatitwilldetect.ThevalidvaluesareAll(thedefault),Off,Critical,Error,Warning,Information,Verbose,andActivityTracing.Thesettingeffectivelymeans"thespecifiedlevelandeverythingmoreimportant."Forexample,theWarningsettingwilldetectwarnings,errors,andcriticalevents.

Formatter Theformattertousewiththistracelistener.Selectonefromthedrop-downlist.Thedefaultisnone.Thisisoptional.

Name Thenameofthetracelistener.ThedefaultisDatabaseTraceListener.Thisisrequired.

TraceOutputOptions

Apropertyusedbytracelistenersthatdonotoutputtoatextformattertodeterminewhichoptions,orelements,shouldbeincludedinthetraceoutput.PossiblevaluesareCallStack,DateTime,LogicalOperationStack,None,ProcessId,ThreadId,andTimestamp.ThedefaultisNone.Foranexplanationofthesevalues,seeTraceOutputOptionsValues.Thisisoptional.

WriteToLogProcedure

Thenameofthestoredprocedurethatwritesthelogentries.ThedefaultisWriteLog.Thisisrequired.

EmailTraceListenerThefollowingtableliststhepropertiesthatyoucansetwhenyouaddane-mailtracelistener.


AuthenticationMode

AvaluefromtheEmailAuthenticationModeenumerationthatspecifieshowthelistenerwillauthenticatetheuser.ValidvaluesareNone,WindowsCredentials,andUserNameAndPassword.

SeverityFilter Appliesafilterthatselectsthelevelofmessagethatitwilldetect.ThevalidvaluesareAll(thedefault),Off,Critical,Error,Warning,Information,Verbose,andActivityTracing.Thesettingeffectivelymeans"thespecifiedlevelandeverythingmoreimportant."Forexample,theWarningsettingwilldetectwarnings,errors,andcriticalevents.

FormatterName

Theformattertousewiththistracelistener.Selectonefromthedrop-downlist.Thedefaultisnone.Thisisoptional.

FromAddress Theaddresswherethelogentryoriginated.Thedefaultisfrom@example.com.Thisisrequired.

Name Thenameofthetracelistener.ThedefaultisEmailTraceListener.Thisisrequired.

AuthenticationPassword

Passwordwhenauthenticatingwithusernameandpassword.

SmtpPort TheSMTPportthatreceivese-mailmessages.Thedefaultis25.Thisisoptional.

SmtpServer TheSMTPserverusedtosende-mailmessages.Thedefaultis127.0.0.1.Thisisoptional.

SubjectLineSuffix

Thesubjectlinesuffix.Thisisoptional.

SubjectLine Thesubjectlineprefix.Thisisoptional.

Prefix

ToAddress Theaddresswherethelogentryissent.Thedefaultisto@example.com.Thisisrequired.

TraceOutputOptions

Tracelistenersthatdonotoutputtoatextformatterusethispropertytodeterminewhichoptions,orelements,shouldbeincludedinthetraceoutput.Possiblevaluesare:CallStack,DateTime,LogicalOperationStack,None,ProcessId,ThreadId,andTimestamp.ThedefaultisNone.Foranexplanationofthesevalues,seeTraceOutputOptionsValues.Thisisoptional.

AuthenticationUserName

Usernamewhenauthenticatingwithusernameandpassword.

UseSSL Specifiesifthee-mailtracelistenershoulduseSSLwhenconnectingtothemailserver.SettoTruetouseSSLtoconnect,orFalsetouseanunencryptedconnection.ThedefaultisFalse

Note:Theconfigurationfilesarenotencryptedbydefault.Aconfigurationfilemaycontainsensitiveinformationaboutconnectionstrings,userIDs,passwords,databaseservers,andcatalogs.Youshouldprotectthisinformationagainstunauthorizedread/writeoperationsbyusingencryptiontechniques.Forinformationabouthowtoencryptconfigurationfiles,seeEncryptingConfigurationDataandConfiguringEnterpriseLibrary.

Inadditiontothisproblem,e-mailmessagesexchangedwithaSMTPservercouldbeinterceptedwhileintransitbyamalicioususerrunninganetworksnifferormonitoringapplication.YoucanmitigatethisproblembysupportingTransportLayerSecurityorS/Mimewithencryptionofthee-mailmessages.

FlatFileTraceListenerThefollowingtableliststhepropertiesthatyoucansetwhenyouaddaflatfiletracelistener.


FileName Thenameofthefilewhereentriesarewritten.Thedefaultnameistrace.log.Thisisarequiredvalue.Itcanincludeenvironmentvariablessuchas%WINDIR%,%TEMP%,and%USERPROFILE%.

SeverityFilter


MessageFooter

Additionalinformationcontainedinthefilefooter.Thedefaultis"----------------------------------------."Thisisoptional.

FormatterName


MessageHeader

Additionalinformationcontainedinthefileheader.Thedefaultis"----------------------------------------."Thisisoptional.

Name Thenameofthetracelistener.ThedefaultisFlatFileTraceListener.Thisisrequired.

TraceOutputOptions


Note:

IfthefileyouspecifyfortheFlatFileTraceListenerisread-only,thetracelistenerdoesnotwritethedatatothefileandnoexceptionoccurs.Makesurethatthefileattributesaresettoread/write.

WhenyouusetheFlatFileTraceListenerclasstowriteloginformationtoafile,theblocklocksthefileuntiltheapplicationcloses.Itispossibletoopenandreadthefile,butyoucannotmoveordeletethelogfileuntilyouclosetheapplication.

EventLogTraceListenerThefollowingtableliststhepropertiesthatyoucansetwhenyouaddaneventlogtracelistener.


SeverityFilter


FormatterName


LogName Thenameoftheeventlogwhereentriesarewritten.ThedefaultisApplication.Thisisoptional.

MachineName

Thenameofthecomputeronwhichtowritelogentries.Thisisoptional.

Name Thenameofthetracelistener.ThedefaultisEventLogTraceListener.Thisisrequired.

SourceName

Thesourcenametousewhenwritingtothelog.ThedefaultisEnterpriseLibraryLogging.Thisisrequired.

TraceOutputOptions


MessageQueuingTraceListenerThefollowingtableliststhepropertiesthatyoucansetwhenyouaddaMessageQueuing(MSMQ)TraceListener.


SeverityFilter Appliesafilterthatselectsthelevelofmessagethatitwilldetect.ThevalidvaluesareAll(thedefault),Off,Critical,Error,Warning,Information,Verbose,andActivityTracing.Thesettingeffectivelymeans"thespecifiedlevelandeverythingmoreimportant."Forexample,theWarningsettingwilldetectwarnings,errors,andcriticalevents.

FormatterName

Theformattertousewiththistracelistener.Selectonefromthedrop-downlist.Thismustbethebinaryformatterwhenyouusethislistenerwiththemessagequeuingdistributorservice.Thisisoptional.

MessagePriority

Setsthepriorityofalogentry.Thisdeterminesitsprioritywhilethelogentryisintransitandwhenitisinsertedintoitsdestinationqueue.PossiblevaluesareAboveNormal,High,Highest,Low,Lowest,Normal,VeryHigh,andVeryLow.ItappliestotheMsmqTraceListenerclass.ThedefaultisNormal.Thisisoptional.

Name Thenameofthetracelistener.ThedefaultisMessageQueuingTraceListener.

QueuePath ThepathtothequeuethattheMsmqTraceListenerinstanceuses.Thisattributeisamessagequeuingpath,anditappliestotheMsmqTraceListenerclass.Thedefaultis.\Private$\myQueue.Thisisrequired.

Recoverable Specifieswhetherthelogentryisguaranteedtobedeliveredifthereisacomputerfailureornetworkproblem.ThedefaultisFalse.Thisisoptional.

TimeToBeReceived

Thetotaltimeforalogentrytobereceivedbythedestinationqueue.Thedefaultis49710.06:28:15.Thisisoptional.

TimeToReachQueue

Themaximumtimeforthelogentrytoreachthequeue.Thedefaultis49710.06:28:15.Thisisoptional.

TraceOutputOptions

Attachesadditionalinformationtoplatform-providedtracelisteneroutputforlistenersthatdonotoutputtoatextformatter.PossiblevaluesareCallStack,DateTime,LogicalOperationStack,None,ProcessId,ThreadId,andTimestamp.ThedefaultisNone.Foranexplanationofthesevalues,seeTraceOutputOptionsValues.Thisisoptional.

TransactionType

ThetypeofaMessageQueuingtransaction.PossiblevaluesareAutomatic,None,andSingle.ItappliestotheMsmqTraceListenerclass.ThedefaultisNone.Thisisoptional.

UseAuthentication

Specifieswhetherthemessagewas(ormustbe)authenticatedbeforebeingsent.ThedefaultisFalse.Thisisoptional.

UseDeadLetterQueue

Specifieswhetheracopyofamessagethatcouldnotbedeliveredshouldbesenttoadead-letterqueue.ThedefaultisFalse.Thisisoptional.

UseEncryption

Specifieswhethertomakethemessageprivate.ThedefaultisFalse.Thisisoptional.

RollingFlatFileTraceListenerThefollowingtableliststhepropertiesthatyoucansetwhenyouaddarollingflatfiletracelistener.Thistracelistenerallowsyoutocontrolthesizeandageofalogfile.


FileName Thisisthenameoftherollingflatfile.Thisisarequiredvalue.Itcanincludeenvironmentvariablessuchas%WINDIR%,%TEMP%,and%USERPROFILE%.IfyoualsosettheMaxArchivedFilesproperty,SeetheadviceonchoosingafilenameinthefollowingRemarkssection.

SeverityFilter


MessageFooter

Additionalinformationcontainedinthefilefooter.Thedefaultis"----------------------------------------."Thisisoptional.

FormatterName


MessageHeader

Additionalinformationcontainedinthefileheader.Thedefaultis"----------------------------------------."Thisisoptional.

MaxArchivedFiles

Themaximumnumberoflogfilestoretain.Whensettoanintegervalue,thetracelistenerwillpurgeoldfilesbasedonthefilecreationdatewhenthenumberexceedsthespecifiedvalue.SeethenoteinthefollowingRemarkssectionifyousetthisproperty.

Name Thisisthenameofthetracelistener.ThedefaultisRollingFlatFileTraceListener.Thisisrequired.

FileExistsBehavior

Thispropertydetermineswhatoccurstoanexistingfilewhenitrollsover.IfyouselectIncrement,theapplicationblock

createsanewfileandnamesitbyincrementingthetimestamp.IfyouselectOverwriteanddonotprovideavaluefortheTimestampPatternproperty,theexistingfileisoverwritten.

RollInterval

Thispropertydetermineswhenthelogfilerollsover.YoucanselectNone(thedefault),Midnight(inwhichcasethelogwillrolloveratmidnight),Minute,Hour,Day,Month,Week,orYear.Thisisoptional.

RollSizeKB

Thisisthemaximumsizethefilecanreach,inkilobytes,beforeitrollsover.Thisisoptional.

TimestampPattern

Thisisthedate/timeformatthatisappendedtothenewfilename(seetheRemarkssectionthatfollowsthistable).

TraceOutputOptions


RemarksIfyousettheMaxArchivedFilesproperty,thistracelistenerwilldelete(purge)filesusingthefilenamepattern[file-name]*.file-extension.Therefore,itwilldeletealllogfilesforanytracelistenerthatmatchesthispatternwhenitpurgesarchivedlogfiles.Topreventthis,useavaluefortheFileNamepropertythatincludedanadditionalperiod.Forexample,use[file-name].[additional-name].file-extension.Youcancontroleitherthesizeofthefile,itsage,orboth.Forexample,ifyouspecifyinconfigurationaRollSizeKBvalueof5KBandaRollIntervalvalueofDay,thefilerollswhenitssizeexceeds5KBanditalsorollsattheendoftheday.IfyouselectIncrementfortheFileExistsBehavior,theapplicationblockcreatesanewfilewhentheexistingfilerollsover.Thefilenameincludesthecurrenttimestamp.Ifafilewiththisnamealreadyexists,theapplicationblockaddsanintegertotheendofthetimestampandincrementsituntilitcannotfindafilewiththatname.Forexample,assumethereisafilenamedmylog2007-01-10.logandthefilerollsoverwhilethattimestampisstillvalid.TheLoggingApplicationBlockwillthenlookforafilenamedmylog2007-01-10.1.log.Ifnosuchfileexists,itwillusethatfilenameforthenewfile.Ifthatfilealsoexists,itwillthenattempttolocatethelogwiththenextsequencenumbermylog2007-01-10.2.log.IfyouselectOverwritefortheFileExistsBehavior,theapplicationblockreplacestheexistingfilewithanewfilewhenthecurrentfilerollsover.However,ifyoualsosettheTimestampPatternproperty,theapplicationblockwillcreateanewfilewiththecurrenttimestampinsteadofreplacingtheexistingfile.If,forsomereason,itcannotoverwritethefile,itwillgenerateanameusingthesameprocessthatisusedwiththeIncrementvalue.RelativepathnamesresolvetoalocationthatisrelativetotheAppDomain.CurrentDomain.BaseDirectorydirectory.

SystemDiagnosticsTraceListenerTheTraceListenerclassprovidestheabstractbaseclassfortracelistenersthatmonitortraceanddebugoutput.ThefollowingtableliststhepropertiesthatappearwhenyouaddaSystemDiagnosticsTraceListener.


InitData Ifsupplied,thispropertyisusedwhentheapplicationblockconstructsatracelistener.Itisastringwhosemeaningdependsonthetypeoftracelistenerbeingconstructed.Forthe.NETFrameworktracelisteners,thestringhasthefollowingvalues:TextWriterTraceListener:filename;XmlWriterListener:filename;DelimitedLIstTraceListener:filename;ConsoleTraceListener:notapplicable;DefaultTraceListener:notapplicable;EventLogTraceListener:eventsourcename.IftheInitDatafieldisnotspecified,theblockusesthedefaultconstructor.IftheuserspecifiestheInitDatafieldforatracelistenerthatdoesnothaveaconstructoroverloadthatacceptsastring,anerroroccurs.Thisisoptional.

Name Thenameofthetracelistener.ThedefaultisSystemDiagnosticsTraceListener.Thisisrequired.

SeverityFilter


TraceOutputOptions


TypeName

Thetypeofthetracelistener.Selectbyclickingtheellipsisbutton(...).ThisopenstheTypeSelector.Thisisrequired.

Note:IfyouspecifyaSystemDiagnosticstracelistenerthatwritestoafileandthatfileisread-only,thetracelistenerdoesnotwritethedatatothefileandnoexceptionoccurs.Makesurethefileattributesaresettoread/write.

WMITraceListenerTheWMItracelistenerisatracelistenerthatraisesaWMImanagementeventforeachlogentryitreceives.ThefollowingtableliststhepropertiesthatyoucansetwhenyouaddaWMITraceListener.


SeverityFilter


Name Thenameofthetracelistener.ThedefaultisWMITraceListener.Thisisrequired.

TraceOutputOptions


XMLTraceListenerThefollowingtableliststhepropertiesthatyoucansetwhenyouaddanXMLTraceListener.


FileName

ThisisthenameofthefilewherethetracelistenerwritesthedataitextractsfromanXmlLogEntryobject.Thisisarequiredvalue.Itcanincludeenvironmentvariablessuchas%WINDIR%,%TEMP%,and%USERPROFILE%.

SeverityFilter


Name Thisisthenameofthetracelistener.ThedefaultisXMLTraceListener.Thisisrequired.

TraceOutputOptions





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Trace Listener Properties'%0AEntLib50_b45ee518-82b1-426c-b772-1e6c0fde455e%0APlease provide details of the error you have located...%0A


TraceOutputOptionsValues

ThefollowingtableliststhepossibleTraceOutputOptionsvalues.

Value Description

Callstack Writethecallstack,whichisrepresentedbythereturnvalueoftheEnvironment.StackTraceproperty.

DateTime Writethedateandtime.

LogicalOperationStack Writethelogicaloperationstack,whichisrepresentedbythereturnvalueoftheCorrelationManager.LogicalOperationStackproperty.

ProcessId Writetheprocessidentity,whichisrepresentedbythereturnvalueoftheProcess.IDproperty.

ThreadId WritetheThreadIdentity,whichisrepresentedbythereturnvalueoftheThread.ManagedThreadIdPropertyforthecurrentthread.

Timestamp Writethetimestamp,whichisrepresentedbythereturnvalueoftheSystem.Diagnostics.Stopwatch.GetTimeStampmethod.

Formoreinformationaboutthesevalues,seeTraceOptionsFieldsinthe.NETFrameworkClassLibraryonMSDN®.



http://msdn2.microsoft.com/en-us/library/system.environment.stacktrace.aspx

http://msdn2.microsoft.com/en-us/library/system.diagnostics.correlationmanager.logicaloperationstack.aspx

http://msdn2.microsoft.com/en-us/library/system.diagnostics.process.id.aspx

http://msdn2.microsoft.com/en-us/library/system.threading.thread.managedthreadid.aspx

http://msdn2.microsoft.com/en-us/library/system.diagnostics.stopwatch.gettimestamp.aspx

http://msdn2.microsoft.com/en-us/library/system.diagnostics.traceoptions.aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'TraceOutputOptions Values'%0AEntLib50_e0902ea8-47a8-465f-a7d4-6809f35f6bc8%0APlease provide details of the error you have located...%0A


ConfiguringWCFIntegrationTraceListeners

WindowsCommunicationFoundation(WCF)isabletologdirectlyonlytoSystem.Diagnosticstracesources,soitisnecessarytoconfigureaspecialtracelistenernamedtheEntLibLoggingProxyTraceListenerinthe<system.diagnostics>configurationsectiontoenabletheLoggingApplicationBlocktoprocessWCFlogmessages.Thistracelistenerreceivesmessagesfromthetracesource,wrapstheminaLogEntryobject,andforwardsthemtotheLoggingApplicationBlock,wheretheycanbeprocessedaccordingtotheLoggingApplicationBlock’sconfiguration.IftheoriginalmessageisinXMLformat(asisthecasewhenmessagesaregeneratedfromWCF),theEntLibLoggingProxyTraceListenercreatesanXmlLogEntryobjectinsteadofaLogEntry.TheXmlLogEntryclassisderivedfromthestandardLogEntryclassandaddssupportforanXMLpayload.

TheEntLibLoggingProxyTraceListenerwilladdthenameofitscontainingtracesourceasacategorytoeachXmlLogEntryitcreates.Inaddition,itispossibletoconfiguretheEntLibLoggingProxyTraceListenertoextractinformationfromtheXMLdataforuseasadditionalcategories.ThiscanbespecifiedusingXPathqueriesinthedefinitionofthetracelistenerintheconfigurationfile.ThecategoriesXPathQueriesattributecanbesettoasemicolon-delimitedlistofXPathqueries,andthenamespacesattributecanbesettoaspace-delimitedlistofXMLnamespacesusedintheXPathqueries,asshowninthefollowingexample.XML

<addname="entlibproxywithmultiplexpaths"

type="Microsoft.Practices.EnterpriseLibrary.Logging.TraceListeners.EntLibLoggingProxyTraceListener,

Microsoft.Practices.EnterpriseLibrary.Logging"

categoriesXPathQueries="//MessageLogTraceRecord/@Source;//MessageLogTraceRecord/@Source2"

namespaces="xmlns:pre='urn:test'xmlns:pre2='urn:test2'"/>

TousetheEntLibLoggingProxyTraceListenerwithWCF,youwillneedtodefineatracesourcenamedSystem.ServiceModelinthe<system.diagnostics>configurationsectionandturnonlogginginWCFby

specifyingappropriatevaluesinthe<diagnostics>sectioninthe<system.serviceModel>configurationsection.NotethattheEnterpriseLibraryconfigurationtoolsdonotsupporteditingeitherofthesesections,soyoumustuseatexteditororalternativeeditor.Formoreinformation,seeSystem.ServiceModelNamespaceonMSDN.FormoreinformationaboutusingtracingwithWCF,seeConfiguringTracingonMSDN.

AlthoughyoucanuseanyofthetracelistenerssupportedbytheLoggingApplicationBlockwithWCF,themostcommonscenarioistologthemessagesinXMLformat.XMLfilesloggedfromWCFcanbeanalyzedintheServiceTraceViewerapplicationthatisincludedintheWindowsSDK.ToconfiguretheLoggingApplicationBlocktologmessagesinthisXMLformat,youshouldusetheXmlTraceListener.ThistracelistenerderivesfromtheXmlWriterTraceListener,whichisapartofthe.NETFramework,andisabletoextracttheXMLpayloadfromanXmlLogEntryobjectandwritethisdatatoanXMLtextfile.YoucananalyzetheoutputofthistracelistenerwiththeWCFlogfileanalysistools.

Asampleconfigurationfilethatdemonstrateswhattheconfigurationshouldlooklikefollowsthenextprocedure.The<system.serviceModel>sectionofthefiledefineshowtheWCFservicebehavesandisnotrelevanttotheactualloggingprocess.

ThefollowingproceduredescribeshowtointegratetheLoggingApplicationBlockwithapplicationsthatuseWCF.

ToconfiguretheWCF-integrationtracelisteners1. CreateoropenaconfigurationfileinoneoftheEnterpriseLibrary

configurationtools,andensuretheLoggingApplicationBlockisaddedtotheapplication’sconfiguration.Formoreinformation,seeConfiguringEnterpriseLibrary.

2. ClicktheplussigniconintheLoggingTargetListenerspane,pointtoAddLoggingTargetListener,andthenclickAddXMLTraceListener.

3. (Optional)Inthepropertiespane,settheName,theFileNameforthetracefile,theSeverityFilterforthelevelofmessagetodetect,andselectavaluefortheTraceOutputOptionspropertytospecifywhichoptionsorelementsshouldbeincludedinthetraceoutput.Formoreinformation,seeTraceOutputOptionsValues.

http://msdn2.microsoft.com/en-us/library/system.servicemodel.aspx


4. ClicktheplussigniconintheCategoriespaneandclickAddCategory.

5. Inthepropertiespane,settheNametoSystem.ServiceModel;setAutoFlushandMinimumSeverityasrequired.

6. ClicktheListenerspropertyplussignicon,thenselecttheXMLTraceListenerfromthedrop-downlist.

7. Savetheconfigurationfile.8. OpentheconfigurationfileeitherinVisualStudio®orinthetexteditor

ofyourchoice.9. DefinetheEntLibProxytracelistenerinthe<system.diagnostics>

sectionanduseSystem.ServiceModelasthesource.(Seethesampleconfigurationfile.)

10. ModifytheWCFconfigurationtospecifythedesiredleveloflogging,asshowninthefollowingsampleconfigurationfile.

XML

<?xmlversion="1.0"encoding="utf-8"?>

<configuration>

<configSections>

<sectionname="loggingConfiguration"

type="Microsoft.Practices.EnterpriseLibrary

.Logging.Configuration.LoggingSettings,

Microsoft.Practices.EnterpriseLibrary.Logging"/>

</configSections>

<loggingConfigurationname="LoggingApplicationBlock"

tracingEnabled="true"

defaultCategory="System.ServiceModel"

logWarningsWhenNoCategoriesMatch="true">

<listeners>

<addfileName="c:\\trace-xml.log"

listenerDataType="Microsoft.Practices.EnterpriseLibrary

.Logging.Configuration.XmlTraceListenerData,


traceOutputOptions="None"

type="Microsoft.Practices.EnterpriseLibrary.Logging

.TraceListeners.XmlTraceListener,


name="XMLTraceListener"/>

</listeners>

<formatters>

</formatters>

<categorySources>

<addswitchValue="All"name="System.ServiceModel">

<listeners>

<addname="XMLTraceListener"/>

</listeners>

</add>

</categorySources>

<specialSources>

<allEventsswitchValue="All"name="AllEvents"/>

<notProcessedswitchValue="All"name="UnprocessedCategory"/>

<errorsswitchValue="All"name="LoggingErrors&Warnings"/>

</specialSources>

</loggingConfiguration>

<system.serviceModel>

<diagnostics>

<messageLogginglogEntireMessage="true"

logMalformedMessages="true"

logMessagesAtTransportLevel="true"/>

</diagnostics>

<services>

<servicename="WCFServiceLibrary1.service1"

behaviorConfiguration="MyServiceTypeBehaviors">

<endpointcontract="WCFServiceLibrary1.IService1"

binding="wsHttpBinding"/>

<endpointcontract="IMetadataExchange"binding="mexHttpBinding"

address="mex"/>

</service>

</services>

<behaviors>

<serviceBehaviors>

<behaviorname="MyServiceTypeBehaviors">

<serviceMetadatahttpGetEnabled="true"/>

</behavior>

</serviceBehaviors>

</behaviors>

</system.serviceModel>

<system.diagnostics>

<sources>

<sourcename="System.ServiceModel"switchValue="All">

<listeners>

<addname="traceListener"

type="Microsoft.Practices.EnterpriseLibrary.Logging

.TraceListeners.EntLibLoggingProxyTraceListener,


</listeners>

</source>

</sources>

</system.diagnostics>

</configuration>

ForinformationabouttheWCF-integrationtracelistenerproperties,seeTraceListenerProperties.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring WCF Integration Trace Listeners'%0AEntLib50_4b216b82-b77d-41c3-bb14-cc1bf5d29db2%0APlease provide details of the error you have located...%0A


ConfiguringFormatters

Thefirstproceduredescribeshowtoconfiguretheformatters.Thetextformatterconvertsalogentryintoatextstring.Thecontentsofthestringaredeterminedbyreplacingtokensinthetextformatter'sTemplateproperty.TheBinaryLogFormatterusesthe.NETFrameworkBinaryFormattertoserializeanddeserializethelogentryinbinaryformat.TheBinaryLogFormatterisrequiredwhenusingtheMessageQueuing(MSMQ)tracelistenerwiththeMessageQueuingdistributorservice.

Toconfigureformatters1. ClickontheplussigniconintheLogMessageFormatterssectionof

theLoggingSettingsconfigurationpaneandclickAddLogMessageFormatterstodisplaythelistofformatters.Whenyouselectaformatter,itisaddedtotheLogMessageFormatterssectionwhereyoucanthensetitsproperties.

2. Clicktheexpanderarrowintheformatteritemyouwishtoconfigureifthepropertiesarenotvisible.

3. (Optional)ChangetheNameproperty.Thedefaultnameisthenameoftheformatter.

4. Ifyouareaddingatextformatterandwanttochangethetemplatethatcontainsthevalueplaceholders,clicktheellipsisbutton(…)fortheTemplateproperty.MaketherequiredchangesintheTemplateEditordialog.YoucanusetheInsertTokenbuttontoaddtokenswiththeappropriatesyntax.Afteryoufinishmakingthechanges,clickOK.

5. IfyouareaddingaCustomFormatterandwanttoaddoreditthesettings,changethelistofkeysandvaluesintheAttributespropertysection.

6. Repeattheprocedureforeachformatteryouwanttouse.Note:

Theonlypropertyyoucanchangeforthebinaryformatteristhename.

TextFormatterTemplateTokensToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://msdn2.microsoft.com/en-us/library/az4se3k1.aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring Formatters'%0AEntLib50_8b4b7563-0062-4690-bfc2-df37f15b2d35%0APlease provide details of the error you have located...%0A


ConfiguringTraceSourceCategories

Tracesourcecategoriesassociatelogentrieswiththeirtargetlistener(s).Youcanconfigurethefollowingtwocategorytypes:

Categoriesthatspecifytheloggingcategoriesyouwanttouse.Whenyoucreatealogentry,youcanassignittooneormorecategories.Eachcategorycanfilterthelogentrybasedonitsseverity(suchasCritical,Error,Warning,orInformation),androuteittooneormoretracelisteners(loggingtargets).SpecialCategoriesthatautomaticallyreceivealllogentries,unprocessedlogentries,orlogentrieswhereanerroroccurredduringlogging.Eachofthesespecialcategoriescanfilterthelogentrybasedonitsseverity(suchasCritical,Error,Warning,orInformation),androuteittooneormoretracelisteners(loggingtargets).

ConfiguringTraceSourceCategories

ConfiguringTraceSourcesSpecialCategory

SourceCategoryProperties

Severity(SourceLevels)ValuesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring Trace Source Categories'%0AEntLib50_9301547d-44c4-490c-91a0-b63e86e4b6a2%0APlease provide details of the error you have located...%0A


ConfiguringLoggingFilters

Youcanfilterlogentriesbasedontheircategoriesandtheirpriorities.Youcanalsoentirelyenableordisableloggingoraddacustomloggingfilter.Thefollowingproceduredescribeshowtoconfiguretheloggingfilters.

Toconfigureloggingfilters1. SelectAddLoggingFiltersasdescribedinConfigurationOverview.2. Ifthefilter'spropertypaneisnotdisplayed,clickthepropertyexpander

arroworright-clickthefiltersnodeyouwishtoconfigure.3. TheCategoryFilterallowsordenieslogentriesbasedontheir

categories:IfyouwanttouseaCategoryFilter,youcanselectthespecificcategoryfilterbyeditingtheCategoriesproperty.Clicktheplussignicontoaddacategoryfilter.Typeorselectthecategorynameforthecategorythatwillbefiltered.Youcaneitherselectanamefromthedrop-downlistortypeacategoryname.AllCategoryFiltersthathavebeenaddedtotheCategoryFilterssectionareavailableforselectioninthedrop-downlist.Theselectedcategorynameappearsinthelowerpane.Repeattoaddanyothercategoriesyourequire.Toremoveacategory,clickthedelete(x)iconbesidethecategoryyouwishtoremove.Repeattoremoveanyothercategoriesyounolongerrequire.Selectafiltermode,eitherAllowAllExceptDeniedorDenyAllExceptDenied.(Optional)Changethenameofthecategoryfilter.ForinformationabouttheCategoryFilterproperties,seeCategoryFilterProperties.

4. TheLoggingEnabledFilterprovidesaglobalswitchthatyoucanusetoturnloggingonandoff:

Ifyouwanttologevents,setAllLoggingEnabledtoTrue.Topreventalllogging,setAllLoggingEnabledtoFalse.(Optional)ChangethenameoftheLoggingEnabledFilter.

ForinformationabouttheLoggingEnabledFilterproperties,seeLoggingEnabledFilterProperties.

5. ThePriorityFilterallowsordenieslogentriesbasedontheirpriority:(Optional)SettheMaximumPriorityproperty.Thisisthemaximumpriorityvaluealogentrycanhaveinordertobelogged.Ifyoudonotsetthisproperty,thevalueis2147483647(thisisthelargestpossiblevalueofa32-bitsignedinteger).(Optional)SettheMinimumPriorityproperty.Thisistheminimumvaluealogentrymusthavetobelogged.Ifyoudonotsetthisproperty,thevalueis-1.(Optional)Changethenameofthepriorityfilter.Forinformationaboutthepriorityfilterproperties,seePriorityFilterProperties.

6. ACustomLoggingFilterisaclassthatyouhavecreatedthatderivesfromtheLogFilterclass.Itsconfigurationinformationconsistsofacollectionofname/valuestringpairs:

SettheTypepropertybyclickingtheellipsisbutton(...)todisplaytheTypeSelector.NavigatetoandclickthefiltertypenameintheTypeSelectordialogbox.YoumustselectaclassthatderivesfromtheLogFilterclass.ItmustalsohavethetypeCustomLogFilterDataspecifiedasthevalueoftheConfigurationElementTypeattributeplacedontheclass.Enterakey/valuepairintheKeyandValuetextboxes.Whenyouenterakey/valuepair,anewpairofblanktextboxesaredisplayed.(Optional)ChangethenameoftheCustomLoggingFilter.ForinformationabouttheCustomLoggingFilterproperties,seeCustomLoggingFilterProperties.

7. Repeattheprecedingstepsforeachfilteryourequire.

CategoryFilterProperties

LoggingEnabledFilterProperties

PriorityFilterProperties

CustomLoggingFilterPropertiesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring Logging Filters'%0AEntLib50_ac913544-cc72-4de9-b916-f9d85d473685%0APlease provide details of the error you have located...%0A


ConfiguringtheApplicationBlock

ThefollowingproceduredescribeshowtoconfiguretheLoggingApplicationBlockproperties.

ToconfiguretheLoggingApplicationBlock1. IntheLoggingSettingssection,clickeachpropertyyouwantto

change.ForinformationabouttheLoggingApplicationBlockproperties,seethetablethatfollowsthisprocedure.

2. Setthepropertiesifyouneedto.Ifyouwanttouseadefaultcategory,clickthedrop-downarrowandselectoneofthecategorynames.Logentriesthatarenotassignedtoacategorybelongtothedefaultcategory.

3. TheWarnIfNoCategoryMatchpropertysendslogentriesthatareassignedtoacategorythatisnotspecifiedinconfigurationtotheLoggingErrors&Warningsspecialsource.ThedefaultisTrue.Ifyoudonotwantthistooccur,clickFalseinthedrop-downlist.

4. TheActivityTracingEnabledpropertyspecifieswhetheractivitytracingisenabled.ThedefaultisTrue.Ifyoudonotwantthistooccur,clickFalseinthedrop-downlist.

LoggingApplicationBlockProperties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring the Application Block'%0AEntLib50_2b5c86d6-f126-4425-9bce-731bb2fcd52d%0APlease provide details of the error you have located...%0A


SourceSchemafortheLoggingApplicationBlock

ThistopicliststheelementsandattributesusedtoconfiguretheLoggingApplicationBlock.Theconfigurationfilehasthefollowingsection-handlerdeclaration.XML

<configSections>

<sectionname="loggingConfiguration"

type="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.LoggingSettings,


</configSections>

Thesection-handlerdeclarationcontainsthenameoftheconfigurationsettingssectionandthenameofthesection-handlerclassthatprocessesconfigurationdatainthatsection.ThenameoftheconfigurationsettingssectionisloggingConfiguration.Thenameofthesection-handlerclassisMicrosoft.Practices.EnterpriseLibrary.Logging.Configuration.LoggingSettings

loggingConfigurationElement

logFiltersChildElement

categoryFiltersChildElement

categorySourcesChildElement

http://msdn2.microsoft.com/en-us/library/system.diagnostics.traceeventtype

listenersChildElement(categorySources)

specialSourcesChildElement

listenersChildElement(errors)

notProcessedChildElement

listenersChildElement(notProcessed)

allEventsChildElement

listenersChildElement(allEvents)

listenersChildElement(loggingConfiguration)

http://msdn2.microsoft.com/en-us/library/system.messaging.messagepriority.aspx

http://msdn2.microsoft.com/en-us/library/system.messaging.messagequeuetransactiontype.aspx

formattersChildElement

msmqDistributorSettingsElement




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Source Schema for the Logging Application Block'%0AEntLib50_12cd1f02-219f-45a3-a711-bd50573de1e4%0APlease provide details of the error you have located...%0A


UsingtheDistributorService

Applicationsmustoftensendlogentriesfrommultiplesourcestoacommondestination.TheLoggingApplicationBlocktakesadvantageofMessageQueuing(alsoknownasMSMQ)toallowyoutodothis.Byconfiguringmultipleapplicationstousethesamemessagequeue,youcanprocesslogentriesatacentrallocation.

Todistributelogentriestoacentraldestination,configureyourapplicationtowritelogentriestothemessagequeuingtracelistener.WhentheapplicationsendsalogentrytotheLoggingApplicationBlock,itplacesthelogentryonaMessageQueuingqueue.ThedistributorservicerunsasaWindowsserviceoneitherthesamecomputerastheapplicationoronaremotecomputer.Itpollsthequeuetoseeifthereareanylogentriesonit.Thepollingintervalisdeterminedbyconfiguration.

Iftherearelogentriesonthequeue,thedistributorserviceusesaninstanceoftheLoggingApplicationBlocktoforwardthemessagestothetracelistener(s).Thetracelistener(s)writethelogentriestothedestinations,suchasaneventlogoraflatfile.

ThedistributorservicerequiresthatalllogentriesbeformattedusingtheBinaryLogFormatterclass.Iftheservicecannotinterprettheentry,itwillloganerrortotheApplicationEventLogandshutdown.

Thefollowingschematicillustrateshowmultipleapplicationsusethedistributorservicetosendlogentriestoacentrallocation.

EachinstanceoftheLoggingApplicationBlockusesaninstanceofthemessagequeuingtracelistener(theMsmqTraceListenerclass)tosendthelogentriestoasingledestinationqueue.ThedistributorservicepollsthequeueandusesanotherinstanceoftheLoggingApplicationBlocktodirectthelogentriestothepropertracelisteners.Notethatthedistributorservicecanrunonaremotecomputer.Thefollowingsectionsdescribeinstallingandusingthedistributorservice:

InstallingtheDistributorServiceStartingtheDistributorServiceUnderstandingtheserviceNameAttribute

InstallingtheDistributorService

http://technet.microsoft.com/en-us/library/cc780048(WS.10).aspx



StartingtheDistributorService

UnderstandingtheserviceNameAttributeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the Distributor Service'%0AEntLib50_ef65d516-04b0-44c2-a750-4e15aab636fd%0APlease provide details of the error you have located...%0A



TheLoggingApplicationBlockisdesignedtosupportthemostcommonscenariosforlogginginformation.Whenaddingyourapplicationcode,refertothescenariosintheKeyScenariossectionsandselecttheonesthatbestsuityoursituation.Usethecodethataccompaniesthescenarioeitherasitisoradaptitasnecessary.

First,prepareyourapplicationtousetheLoggingApplicationBlock.ThefollowingproceduredescribeshowtoincludethenecessaryEnterpriseLibraryassembliesandelementsinyourcode.

Toprepareyourapplication1. SetareferencetotheLoggingApplicationBlockassembly:

IfyouareusingC#,inVisualStudio,right-clickReferencesinSolutionExplorer,andthenclickAddReferencestoaddreferencestothefollowingassemblies:

Microsoft.Practices.Unity.dllMicrosoft.Practices.Unity.Interception.dllMicrosoft.Practices.ServiceLocation.dllMicrosoft.Practices.EnterpriseLibrary.Common.dllMicrosoft.Practices.EnterpriseLibrary.Logging.dll

IfyouareusingVisualBasic®,double-clickMyProjectinVisualStudio,clicktheReferencestab,andthenclickAddReferencetoselecttheassembly.Inthelistofimportednamespacesatthebottomofthetab,selectthefollowingcheckboxes:

Microsoft.Practices.Unity.dllMicrosoft.Practices.Unity.Interception.dllMicrosoft.Practices.ServiceLocation.dllMicrosoft.Practices.EnterpriseLibrary.Common.dllMicrosoft.Practices.EnterpriseLibrary.Logging.dll

2. (Optional)TouseelementsfromtheLoggingApplicationBlockwithoutfullyqualifyingtheelementreference,youcanaddthefollowingusingstatements(C#)orImportsstatements(VisualBasic)tothetopofyoursourcecodefile.

C#

usingMicrosoft.Practices.EnterpriseLibrary.Logging;

usingMicrosoft.Practices.EnterpriseLibrary.Logging.ExtraInformation;

usingMicrosoft.Practices.EnterpriseLibrary.Logging.Filters;

VisualBasic

ImportsMicrosoft.Practices.EnterpriseLibrary.Logging

ImportsMicrosoft.Practices.EnterpriseLibrary.Logging.ExtraInformation

ImportsMicrosoft.Practices.EnterpriseLibrary.Logging.Filters

Note:ForVisualBasicprojects,youcanalsousetheReferencespageoftheProjectDesignertomanagereferencesandimportednamespaces.ToaccesstheReferencespage,selectaprojectnodeinSolutionExplorer,andthenclickPropertiesontheProjectmenu.WhentheProjectDesignerappears,clicktheReferencestab.

TheExtraInformationprovidersgathercontextinformationthatisusefulbutnotalwaysnecessarybecauseitisexpensivetocollect.ExamplesarestacktraceinformationandCOM+information.TheExtraInformationprovidersaddtheinformationtoadictionary.Youcanchoosewhichproviderstouse(ifany)andaddtheresultingdictionarytotheLogEntry.ExtendedPropertiesproperty.Filtersareoptional.YouonlyneedtoimporttheMicrosoft.Practices.EnterpriseLibrary.Logging.Filtersnamespaceifyouaregoingtorefertospecificfiltersinyourapplicationcode.

3. IfyouareusingtheDatabaseTraceListenerclass,youmustalsodothefollowing:

ConfiguretheapplicationtousetheDataAccessApplicationBlock.Formoreinformation,seeTheDataAccessApplicationBlock.ExecutethescriptnamedCreateLoggingDb.cmd(locatedintheSource\Blocks\Logging\Src\DatabaseTraceListener\Scriptsfolder)tocreatetheLoggingdatabase.

Note:ItisalsoagoodideatoaddareferencetotheMicrosoft.Practices.EnterpriseLibrary.Logging.Database.dlltoyourprojectsothattheassemblyrequiredatruntimeiscopiedtotheoutputfolder.

4. Addtheapplicationcode.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Application Code'%0AEntLib50_730d69d7-7e0f-4b21-8ab8-725bcec1bfd3%0APlease provide details of the error you have located...%0A


KeyScenarios

Thisseriesoftopicsdescribescommonsituationsdevelopersmustaddresswhenprovidingloggingfunctionalityintheirapplications.Eachscenarioexplainsthetask,describesareal-worldsituationwheresuchataskmightarise,andincludescodedemonstratinghowtousetheLoggingApplicationBlocktocompletethetask.Thescenariosareasfollows:

LoggingtoaDatabase.ThistopicdescribestheprocessyoushouldfollowforusingtheLoggingApplicationBlocktoimplementthecommonrequirementofloggingtoadatabase.LoggingtoWindowsEventLog.ThistopicdescribestheprocessyoushouldfollowforusingtheLoggingApplicationBlocktoimplementthecommonrequirementofloggingtoWindowsEventLog.LoggingtoaDiskFile.ThistopicdescribestheprocessyoushouldfollowforusingtheLoggingApplicationBlocktoimplementthecommonrequirementofloggingtoadiskfile.LoggingtoWindowsMessageQueuing.ThistopicdescribestheprocessyoushouldfollowforusingtheLoggingApplicationBlocktoimplementthecommonrequirementofloggingtoWindowsMessageQueuing.LoggingtoWMI.ThistopicdescribestheprocessyoushouldfollowforusingtheLoggingApplicationBlocktoimplementthecommonrequirementofloggingtotheWindowsManagementInstrumentationrepository.LoggingasE-mailMessages.ThistopicdescribestheprocessyoushouldfollowforusingtheLoggingApplicationBlocktoimplementthecommonrequirementofsendinglogginginformationine-mailmessages.PopulatingandRaisingEventsfromCode.Thisscenarioillustrateshowtowritecodetospecifythedatatobelogged,alongwithacategoryandpriority,andpassittotheapplicationblock.PopulatingaLogMessagewithAdditionalContextInformation.Thisscenarioillustrateshowtopopulateadictionaryofcustominformationtobeaddedtoalogentry.TracingActivitiesandPropagatingContextInformation.Thisscenarioillustrateshowtologthestartandendofanactivityandtracekeyactivitypointsinbetween.

CheckingFilterStatusbeforeConstructingLogMessages.Thisscenarioillustrateshowtoavoidcollectingloginformationformessagesthatwillnotbeloggedaccordingtothecurrentconfigurationinformation.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Key Scenarios'%0AEntLib50_33d9998d-fa92-40b4-be49-7e28a72bd22c%0APlease provide details of the error you have located...%0A


LoggingtoaDatabase

ThisscenarioisoneofseveralthatdescribethetypicalrequirementswhenusingtheLoggingApplicationBlockinyourapplications.Itdescribestheprocessforsettinguptheblocktosendlogeventstoadatabase.Theprocessinvolvesconfiguringtheblockandperformingothertaskstoprepareyourapplication.ThistopicactsasareferencetohelpyouquicklysetuptheLoggingApplicationBlocktoperformtherequiredloggingaction.

TypicalGoals

SolutionToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging to a Database'%0AEntLib50_b010d39c-5196-439a-8d7c-92d6cbe1d892%0APlease provide details of the error you have located...%0A


LoggingtoWindowsEventLog

ThisscenarioisoneofseveralthatdescribethetypicalrequirementswhenusingtheLoggingApplicationBlockinyourapplications.ItdescribestheprocessforsettinguptheblocktosendlogeventstoWindowsEventLog.Theprocessinvolvesconfiguringtheblockandperformingothertaskstoprepareyourapplication.ThistopicactsasaquickreferencetohelpyourapidlysetuptheLoggingApplicationBlocktoperformtherequiredloggingaction.

TypicalGoals



http://msdn.microsoft.com/en-us/library/system.diagnostics.eventloginstaller(VS.71).aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging to Windows Event Log'%0AEntLib50_45e42198-6a44-4d0b-bb55-691b7c5ed2bf%0APlease provide details of the error you have located...%0A


LoggingtoaDiskFile

ThisscenarioisoneofseveralthatdescribethetypicalrequirementswhenusingtheLoggingApplicationBlockinyourapplications.Itdescribestheprocessforsettinguptheblocktosendlogeventstoadiskfile.Theprocessinvolvesconfiguringtheblockandperformingothertaskstoprepareyourapplication.ThistopicactsasaquickreferencetohelpyouquicklysetuptheLoggingApplicationBlocktoperformtherequiredloggingaction.

TypicalGoals




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging to a Disk File'%0AEntLib50_d0234cae-d49b-44b0-9f0c-bb79089022af%0APlease provide details of the error you have located...%0A


LoggingtoWindowsMessageQueuing

ThisscenarioisoneofseveralthatdescribethetypicalrequirementswhenusingtheLoggingApplicationBlockinyourapplications.ItdescribestheprocessforsettinguptheblocktosendlogeventsasmessagesthroughWindowsMessageQueuing.Theprocessinvolvesconfiguringtheblockandperformingothertaskstoprepareyourapplication.ThistopicactsasaquickreferencetohelpyouquicklysetuptheLoggingApplicationBlocktoperformtherequiredloggingaction.

TypicalGoals




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging to Windows Message Queuing'%0AEntLib50_7dd3bd7e-c463-4dbd-92f8-472e0eab8d53%0APlease provide details of the error you have located...%0A


LoggingtoWMI

ThisscenarioisoneofseveralthatdescribethetypicalrequirementswhenusingtheLoggingApplicationBlockinyourapplications.ItdescribestheprocessforsettinguptheblocktosendlogeventstotheWindowsManagementInstrumentationdatabase.Theprocessjustinvolvesconfiguringtheblock—therearenoothertasksrequiredtoprepareyourapplication.ThistopicactsasaquickreferencetohelpyouquicklysetuptheLoggingApplicationBlocktoperformtherequiredloggingaction.

TypicalGoals




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging to WMI'%0AEntLib50_5a06c55e-f2c0-49db-9486-af121f8ac4db%0APlease provide details of the error you have located...%0A


LoggingasE-mailMessages

ThisscenarioisoneofseveralthatdescribethetypicalrequirementswhenusingtheLoggingApplicationBlockinyourapplications.Itdescribestheprocessforsettinguptheblocktosendlogeventsase-mailmessages.Theprocessinvolvesconfiguringtheblockandperformingothertaskstoprepareyourapplication.ThistopicactsasaquickreferencetohelpyourapidlysetuptheLoggingApplicationBlocktoperformtherequiredloggingaction.

TypicalGoals




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging as E-mail Messages'%0AEntLib50_c28f7cd6-7933-47ba-8d30-ac4ecaa96a52%0APlease provide details of the error you have located...%0A


PopulatingandRaisingEventsfromCode

TheabilitytopopulateandraiseeventsfromcodeisfundamentaltothefunctionalityoftheLoggingApplicationBlock.

TypicalGoals

Solution





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Populating and Raising Events from Code'%0AEntLib50_3712145d-7fa5-4fd7-b9a7-ea2d018b5fc7%0APlease provide details of the error you have located...%0A


PopulatingaLogMessagewithAdditionalContextInformation

TheLogEntryclassdefinespropertiestoholdinformationcommontotypicalloggingscenarios.Developersoftenneedtoaddcontextinformationtologentries.Thesametypeofcontextinformationcanberequiredformultiplelogentriesinthesameapplicationorinmultipleapplications.Becausecontextinformationcanbeexpensivetogather,certaintypesofinformationarenotautomaticallycollected.TheExtraInformationprovidersgathercontextinformationthatisusefulbutnotalwaysnecessarybecauseitisexpensivetocollect.ExamplesarestacktraceinformationandCOM+information.

TypicalGoals

Solution




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Populating a Log Message with Additional Context Information'%0AEntLib50_62843eda-e525-4531-8d26-4efddd75ccef%0APlease provide details of the error you have located...%0A


TracingActivitiesandPropagatingContextInformation

Insomecases,youwillneedtologinformationatthestartandendofaparticularactivity,includingtiminginformation.Inaddition,youcantracetheprogressoftheactivityatselectedpointsintheapplication.TracingallowsyoutoassociatealleventsbetweenthestartandendofanactivitywithanActivityIDpropertyandacategory.TheActivityIDpropertyallowsyoutocorrelatelogentriesthatarewrittenduringtheexecutionofanactivity.Youcanusefiltersandcategoriestodirectandcontroltheinformationproducedforaneventthatcanoccurinthecontextofanyactivity.

TypicalGoals

Solution





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Tracing Activities and Propagating Context Information'%0AEntLib50_76ae5d88-2ad5-4d53-a727-c8f80807d6d1%0APlease provide details of the error you have located...%0A


CheckingFilterStatusbeforeConstructingLogMessages

ByusingtheLoggingApplicationBlock,youcanquerythefilterstatustodeterminewhetheralogmessageshouldbeloggedaccordingtothefilterconfiguration.

TypicalGoals

Solution




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Checking Filter Status before Constructing Log Messages'%0AEntLib50_37d65dcf-7447-46f6-97ec-6208b9a317b6%0APlease provide details of the error you have located...%0A


DesignoftheLoggingApplicationBlock

TheLoggingApplicationBlockincludesthefollowingfeatures:AsimpleandconsistentwayofloggingeventinformationDistributionofinformationtomultiplesourcesActivitytracingtomarkthestartandendofanactivitysuchasausecaseSimplifiedapplicationblockconfigurationusingtheconfigurationtoolsExtensibilitythroughcustomtracelistenersandformatters

DesignGoals

DesignHighlights




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Logging Application Block'%0AEntLib50_47589a17-a0d7-4651-93e1-41b9bc975eb6%0APlease provide details of the error you have located...%0A


DesigningforSimpleandConsistentLoggingFunctionality

Developersfacemanyimplementationchoicesandrequirementswhentheyaddloggingfunctionalitytotheirapplications.Differentapplicationsmayloginformationtodifferentdestinations.Forexample,oneapplicationmayuseaneventlogandanotherapplicationmayuseaflatfile.Evenasingleapplicationmayloginformationtomultipledestinations.Asaresult,developersmustoftenwriteduplicatecodeforcommontaskssuchaswritingtoaneventlogortoaflatfile.

Uniformimplementationsmakethecodeeasiertounderstand,morepredictable,andeasiertomaintain.However,differentdevelopmentteamsroutinelyimplementdifferentloggingstrategies.TheLoggingApplicationBlockencapsulatesthelogicthatperformsloggingandtracingoperationsintoafewclassesthathavesmallnumbersofmethods.Thesemethodsarethesameforalllogmessagedestinations.ThismeansthatapplicationsthatusetheLoggingApplicationBlockareconsistentinthewaysthattheyloginformation.ByusingtheLoggingApplicationBlock,thisconsistencyremainsacrosssingleprojects,multipleprojects,orenterprise-scalesolutions.

DesignImplications




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Designing for Simple and Consistent Logging Functionality'%0AEntLib50_1ee4fccf-170c-4650-8282-c46e86902a17%0APlease provide details of the error you have located...%0A


ExtendingandModifyingtheLoggingApplicationBlock

Initsoriginalstate,theLoggingApplicationBlockworkswellfortypicalloggingscenarios.However,theremaybetimeswhenyouneedtocustomizesomeoftheapplicationblock'sbehaviortobettersuityourapplication'sparticularrequirements.Therearetwowaystodothis:youcanextendtheLoggingApplicationBlockusingthebuilt-inextensionpointsoryoucanmodifytheapplicationblockbymakingchangestoitssourcecode.Formoredetails,seethefollowingtopics:

ExtendingtheLoggingApplicationBlockExtendingandModifyingEnterpriseLibrary




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying the Logging Application Block'%0AEntLib50_5d44c59c-4981-431a-aa38-5f466d4586c7%0APlease provide details of the error you have located...%0A


ExtendingtheLoggingApplicationBlock

TheLoggingApplicationBlockisdesignedtosuitavarietyofapplicationsandtoprovidethemostcommonlyusedloggingfunctions.Youcanextendtheapplicationblockthroughdesignatedextensionpoints.Typically,thesearecustomclasses,writtenbyyou,thatimplementaparticularinterfaceorderivefromanabstractclass.Becausethesecustomclassesexistinyourapplicationspace,youdonotneedtomodifyorrebuildtheapplicationblock.Instead,youdesignateyourextensionsusingconfigurationsettings.Additionally,withextensionpoints,youcanadapttheapplicationblocktosuittheneedsofanyparticularapplication.

Youcanextendthecapabilitiesoftheblockbyaddingcustomformatters,tracelisteners,andlogfilters.


LogEntryFormatter ILogFormatter

TraceListener CustomTraceListener

LogFilter ILogFilterLogFilter


ThefollowingproceduredescribesthegeneralapproachtoextendtheLoggingApplicationBlock.

ToextendtheLoggingApplicationBlock1. Createanewcustomclassandaddittoyourproject.2. Makesurethattheclassimplementstherequiredinterfaces,

constructors,andmethods.3. AddthecustomobjecttotheconfigurationoftheLoggingApplication

BlockusingtheEnterpriseLibraryconfigurationtools:Specifyyourcustomclassasthetypename.

Specifyanycustomconfigurationpropertiesbymodifyingtheattributesoftheobject.

CreatingaCustomLogEntryFormatter

CreatingaCustomTraceListener

CreatingaCustomLogFilterToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending the Logging Application Block'%0AEntLib50_bca61231-bddd-4531-b797-449dfc0639e8%0APlease provide details of the error you have located...%0A



Twoofanadministrator'smaintaskswillbetoseethattheinitialdeploymentoftheLoggingApplicationBlockisplannedandmanagedandthatsubsequentupdatesaredeployedwithminimalimpacttoexistingapplicationsthatusetheapplicationblock.FordetailsofdeployingandupdatingEnterpriseLibraryandtheapplicationblocks,seeDeployingEnterpriseLibrary.

Inaddition,administratorsmustdecidewhethertheywanttousetheinstrumentationexposedbytheapplicationblock.Fordetailsofhowtoenableanddisableinstrumentation,seeEnablingInstrumentation.ForinformationabouttheinstrumentationcontainedintheLoggingApplicationBlock,seethefollowingtopics:

LoggingApplicationBlockPerformanceCountersLoggingApplicationBlockEventLogEntries




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deployment and Operations'%0AEntLib50_11aa70e5-da29-457d-8600-a7507ff538dd%0APlease provide details of the error you have located...%0A


LoggingApplicationBlockPerformanceCounters

ThefollowingtabledescribestheLoggingApplicationBlockperformancecounters.


Description

Avg.TraceExecutionTime

Theaverageexecutiontimefortracedoperations.

LoggingEventsRaised/sec

Therateatwhichloggingeventswereraised.

TotalLoggingEventsRaised

Thetotalnumberofloggingeventsraised.

TotalTraceListenerEntriesWritten

Thetotalnumberofentriesthatweretracedbyindividualtracelisteners.

TotalTraceOperationsStarted

Thetotalnumberoftracingoperationsstarted.

TraceListenerEntriesWritten/sec

Therateatwhichlogentriesweretracedbyindividualtracelisteners.

TraceOperationsStarted/sec

Therateatwhichtracingoperationswerestarted.

Anaveragecountermeasuresavalueovertimeanddisplaystheaverageofthelasttwomeasurements.Aratecountersamplesanincreasingcountofeventsovertimeanddividesthevaluesbythechangeintimetodisplayarateofactivity.Formoreinformationaboutperformancecounters,seeOverviewofPerformanceMonitoringinthe.NETFrameworkClassLibraryonMSDN.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging Application Block Performance Counters'%0AEntLib50_9cf95b26-a4e5-459f-9086-ea45b5682bae%0APlease provide details of the error you have located...%0A



LoggingApplicationBlockEventLogEntries

ThistopicliststheLoggingApplicationBlockeventlogentries.Thelisteneristheclassthatraisedtheevent.

FailureLoggingErrorEvent

LockAcquisitionErrorEvent




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Logging Application Block Event Log Entries'%0AEntLib50_453fc467-c49f-4958-8449-d4ad4682dff5%0APlease provide details of the error you have located...%0A


ThePolicyInjectionApplicationBlock

Policyinjectioncanbeusedtochangethebehaviorofyourcustomobjects,andalmostanyother.NETclass,inordertobettermanagecrosscuttingconcernsfortheseobjects.InthecurrentversionofMicrosoft®EnterpriseLibrary,policyinjectionisimplementedthroughtheUnityinterceptionmechanism.FormoreinformationseeInterceptionwithUnity.

WhilethePolicyInjectionApplicationBlockisstillincludedinthisreleaseofEnterpriseLibrary,itis(withtheexceptionofonecallhandler)asetoflegacycomponentssuchasthePolicyInjectionfacadethatsupportsbackwardscompatibilitywithapplicationsthatuseversionsofEnterpriseLibrarypriortoversion5.0.

Forinformationabouttheselegacycomponents,seetheguidanceforpreviousversionsofEnterpriseLibrary.ThisisavailableontheMicrosoftEnterpriseLibrarysiteonMSDN®,andincludesspecificinformationforCreatinganInstanceofanInterceptableTargetClass,detailsonusingthecreatemethod,detailsonusingthewrapmethod,andSpecifyingaConfigurationInstanceWhenCreatingandWrappingObjects.Youcan,inaddition,usetheconfigurationtoolsprovidedwiththisreleaseofEnterpriseLibrarytoconfigurepolicyinjectionifyoudecidetousethelegacyapproach.

Alsobeawarethat,evenifyoudecidetocontinuetousethebackwardscompatibilitytechniquesincludedinthePolicyInjectionApplicationBlock,youmuststillmakesomechangestoyourexistingapplication.Thelocationofallofthecallhandlers(withtheexceptionofthePerformanceCounterHandler)haschanged,soyoumustensurethatyoureferencetheappropriateassembliesandnamespacesinyourcode.

Thefivecallhandlersyoucanuse,andtheirassembliesandnamespacesare:Authorizationhandler

Classname:AuthorizationCallHandlerAssembly:Microsoft.Practices.EnterpriseLibrary.Security.dllNamespace:Microsoft.Practices.EnterpriseLibrary.Security.PolicyInjection

Exceptionhandlinghandler






Classname:ExceptionCallHandlerAssembly:Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.dllNamespace:Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.PolicyInjection

LogginghandlerClassname:LogCallHandlerAssembly:Microsoft.Practices.EnterpriseLibrary.Logging.dllNamespace:Microsoft.Practices.EnterpriseLibrary.Logging.PolicyInjection

ValidationhandlerClassname:ValidationCallHandlerAssembly:Microsoft.Practices.EnterpriseLibrary.Validation.dllNamespace:Microsoft.Practices.EnterpriseLibrary.Validation.PolicyInjection

PerformancecounterhandlerClassname:PerformanceCounterCallHandlerAssembly:Microsoft.Practices.EnterpriseLibrary.PolicyInjection.dllNamespace:Microsoft.Practices.EnterpriseLibrary.PolicyInjection.CallHandlers

TheCachinghandlerisnolongerincludedinEnterpriseLibraryduetoconcernsaroundtheissuesofcachecontaminationandotherlimitationspreviouslydocumented.IfyourequiretheCachinghandler,youcandownloadthepreviousversionfromtheEnterpriseLibrarycommunityWebsiteathttp://www.codeplex.com/entlib/andintegrateitwithEnterpriseLibrary.

MoreinformationaboutthechangestothePolicyInjectionApplicationBlockcanbefoundinthesectionChangesinThisReleaseintheintroductiontothisguidance.InformationaboutmigratingexistingapplicationstousethecurrentversionofEnterpriseLibrarycanbefoundintheMigrationGuideavailablefromtheEnterpriseLibrarycommunityWebsiteathttp://www.codeplex.com/entlib/.





[email protected].


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Policy Injection Application Block'%0AEntLib50_a083e2d0-9020-4482-9d2d-2eae696d2f9f%0APlease provide details of the error you have located...%0A


TheSecurityApplicationBlock

DevelopersfrequentlywriteapplicationsthatmustauthorizeusersusingoneormoresecurityproviderssuchasMicrosoft®ActiveDirectory®directoryservice,AuthorizationManager,ActiveDirectoryLightweightDirectoryServices(ADLDS),andcustomauthorizationproviders.Theseapplicationsmayalsoneedtocacheauthenticationorauthorizationdataforthedurationofalogonsession.

TheSecurityApplicationBlocksimplifiesthesetasksbyhandlingtheminaconsistentmanner,abstractingtheapplicationcodefromthespecificsecurityproviders.Youcanevenchangeunderlyingprovidersthroughconfigurationwithoutchangingtheunderlyingapplicationcode.

TheSecurityApplicationBlockprovidescodethatwillhelpyouwiththefollowingscenarios:

AuthorizationCachingsecurity-relatedcredentials

ThissectionincludesthefollowingtopicsthatwillhelpyoutounderstandandusetheSecurityApplicationBlock:

WhatDoestheSecurityApplicationBlockDo?Thistopicprovidesabriefoverviewthatwillhelpyoutounderstandwhattheblockcando,andexplainssomeoftheconceptsandfeaturesitincorporates.Italsoprovidesasimpleexampleofthewaythatyoucanwritecodetousetheblock.WhenShouldIUsetheSecurityApplicationBlock?Thistopicwillhelpyoutodecideiftheblockissuitableforyourrequirements.Itexplainsthebenefitsofusingtheblock,andanyalternativetechniquesyoumayconsider.Italsoprovidesdetailsofanylimitationsoftheblockthatmayaffectyourdecisiontouseit.DevelopingApplicationsUsingtheSecurityApplicationBlock.ThistopicexplainshowtoconfiguretheSecurityApplicationBlocktoperformcommontasksandhowtousetheblockinyourapplications.KeyScenarios.ThistopicdemonstrateshowtousetheSecurityApplicationBlocktoperformthemosttypicalsecurityoperations.DesignoftheSecurityApplicationBlock.Thistopicexplainsthe

decisionsthatwentintodesigningtheSecurityApplicationBlockandtherationalebehindthosedecisions.ExtendingandModifyingtheSecurityApplicationBlock.Thistopicexplainshowtoextendtheblockbycreatingyourownprovidersandhowtomodifythesourcecode.DeploymentandOperations.ThistopicexplainshowtodeployandupdatetheSecurityApplicationBlock'sassembliesandalsocontainsinformationaboutconfiguration.

MoreInformationFormoreinformation,seethefollowingpatterns&practicesguides:

ApplicationArchitecturefor.NET:DesigningApplicationsandServices.NETDataAccessArchitectureGuideDesignGuidelinesforExceptions







mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Security Application Block'%0AEntLib50_0468b82a-15db-41bd-ad9a-cbe44a448d8b%0APlease provide details of the error you have located...%0A


WhatDoestheSecurityApplicationBlockDo?

TheSecurityApplicationBlockallowsyoutoperformtwoseparatebutrelatedtasks.Youcanauthorizeusersagainstarangeofauthorizationproviders,and/orcacheauser'sidentityandsecuritycontextforusethroughoutyourapplication.Thecoderequiredtousethesefeaturesissimple,andtheactualmechanicsofaccessingauthorizationsystemsandcachingidentitiesandsecuritycontextsareabstractedwithintheblock.Often,youonlyneedtowriteonelineofcodetoperformcommontasks.ThefollowingschematicshowsthebasicelementsoftheSecurityApplicationBlock.

TheSecurityApplicationBlockexposestwointerfacesthatyoucanaccessinyourcode:

AnAuthorizationProviderinterface,whichexposesthesinglemethodnamedAuthorizethattakesaninstanceofanIPrincipalobjectcontainingdetailsoftheuser'sidentityandroles.Dependingonthewaythatyouconfiguretheblock,theauthorizationcantakeplaceeitherthroughWindows®AuthorizationManager(AzMan)againstActive

Directory,anXMLfile,oradatabase;orbyusingcustomrulesthatyoudefineandarestoredasXMLintheapplicationconfigurationfile.ASecurityCacheProviderinterface,whichexposesmethodsthatallowyoutosaveandretrieveauser'sidentityorsecuritycontextasanIIdentityinstance,IPrincipalinstance,orASP.NETProfileinstance.Eachcachedidentityorsecuritycontextisidentifiedbyatoken(bydefaultaGUID,thoughyoucancreateanduseyourownimplementationoftheITokeninterface).TheblockstoresthisinformationineitheradatabaseorinIsolatedStorageusingtheCachingApplicationBlock.YoucanalternativelycreateacustomproviderfortheCachingApplicationBlockanduseittocachetheinformationinthelocationandusingthetechniquesyouimplementinyourprovider.

Yourapplicationcanusetheseinterfacestoquicklyandeasilycacheuseridentitiesandsecuritycontexts,obtaintokensthatrepresentusers,expiretheseusers,andcheckifusersareauthorizedtoperformspecifictasksoroperations.However,togetthemostfromtheblock,youmustunderstandthedifferencesbetweentheWindowsIIdentityandIPrincipalinterfacesandcommonlyusedconcreteimplementationsofthesetypes.

AnidentityisrepresentedbyaconcreteimplementationoftheIIdentityinterface,usuallyaWindowsIdentity,GenericIdentity,PassportIdentity,orFormsIdentitydependingontheauthenticationtechniqueused.TheIPrincipalinterfaceprovidesthelinkbetweenanidentityandtherolesforthatidentity.InASP.NET,thecurrentIPrincipalinstanceforauserisavailablefromtheHttpContext.Userproperty.ThemethodsthatcacheandretrieveuseridentityandsecuritycontextacceptaninstanceofaclassthatimplementseithertheIIdentityorIPrincipalinterface,oranASP.NETProfileinstance.FormoreinformationaboutWindowsidentitiesandsecuritycontexts,seePrincipalandIdentityObjectsandRole-BasedSecurityonMSDN®.

http://msdn.microsoft.com/en-us/library/ftx85f8x(VS.80).aspx

http://msdn.microsoft.com/en-us/library/52kd59t0(VS.80).aspx

TypicalUsageoftheSecurityApplicationBlock




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Does the Security Application Block Do?'%0AEntLib50_2042b096-612e-40c6-8990-c54d462e5ee6%0APlease provide details of the error you have located...%0A


WhenShouldIUsetheSecurityApplicationBlock?

TheSecurityApplicationBlockincludesimplementationsoffunctionalitythatmakesiteasytoperformauthorization,security-relatedcaching,andsessionmanagement.Ifyourapplicationsrequiretheprovidedimplementations,youcanusetheSecurityApplicationBlocktoprovidethisfunctionality.However,theblockisalsodesignedtobeextensibleandincludesgenericprovidersforeachfunction.Youcanadapttheproviderstomeetyourownsecurityrequirements.

ScenariosfortheSecurityApplicationBlock

BenefitsoftheSecurityApplicationBlock

LimitationsoftheSecurityApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'When Should I Use the Security Application Block?'%0AEntLib50_a9d4059d-2a26-4785-885b-e1160e914ed9%0APlease provide details of the error you have located...%0A


DevelopingApplicationsUsingtheSecurityApplicationBlock

ThistopicdescribeshowyoucanusetheSecurityApplicationBlocktodevelopapplications.Itexplainshowtoconfiguretheblockandincorporateitintoyourapplications,andhowtousetheblockforspecificscenariossuchasauthorizingauserforaparticulartask.ThistopicassumesthatyouareusingtheSecurityApplicationBlockinitsoriginalstate,withoutextendingit.(Tolearnhowtoaddfunctionality,seeExtendingtheSecurityApplicationBlock.)Thissectionincludesthefollowingtopics:

EnteringConfigurationInformationAddingApplicationCode

Allapplicationblocksshipasbinaryassembliesandassourcecode.Ifyouwanttousethesourcecode,youmustcompile.TolearnhowtocompiletheEnterpriseLibrarysourcecode,seeBuildingEnterpriseLibraryfromtheSourceCode.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Developing Applications Using the Security Application Block'%0AEntLib50_b9f4b643-f8bf-47b3-bc7d-498315e3480e%0APlease provide details of the error you have located...%0A



TheseproceduresexplainhowtoconfiguretheSecurityApplicationBlock.FordetailsoftheschemafortheSecurityApplicationBlockconfiguration,seeSourceSchemafortheSecurityApplicationBlock.Youcanalsoconfiguretheblockincodebyusinganalternateconfigurationsource.Formoreinformation,seeAdvancedConfigurationScenariosandUsingtheFluentConfigurationAPI.

ToaddtheSecurityApplicationBlock1. Opentheconfigurationfile.Formoreinformation,seeConfiguring

EnterpriseLibrary.2. ClickAddSecuritySettingsontheBlocksmenu.3. TheconfigurationtoolautomaticallyaddstheSecuritySettingssection

withdefaultsettings.ClickthechevronarrowattherightofthesectionheadingtoviewSecuritySettingsproperties.

4. ClicktheAuthorizationProvidersplussignicon,pointtoAddAuthorizationProviders,thenclickthetypeofauthorizationruleprovideryourequireandconfiguretheproviderasshowninthefollowingprocedures.Note:

TheWindowsAuthenticationManager(AzMan)providerisavailableonlyifyouhaveinstalledtherequiredprerequisites,includingtheassemblyMicrosoft.Interop.Security.AzRoles.dll,andcompiledtheSecurityApplicationBlocktoincludethisprovider.Formoreinformation,seeAbouttheAzManProviderlaterinthistopic.

5. (Optional)ClicktheSecurityCachesplussignicon,pointtoAddSecurityCaches,thenclickthetypeofsecuritycacheprovideryourequireandconfiguretheproviderasshowninthefollowingprocedures.

6. (Optional)InthepropertiespaneoftheSecuritySettingssection,settheProtectionProviderproperty.Thetextboxdrop-downprovidesthreechoices(noprotection),RsaProtectedConfigurationProvider,andDataProtectionConfigurationProvider.Thedefaultisnoprotection.SeeEncryptingConfigurationDataforinformationabout

therestrictionsonusingtheRsaProtectedConfigurationProvider.7. (Optional)Inthepropertiespane,settheRequirePermissionproperty

toTrueorFalse.ThedefaultisTrue.8. (Optional)Inthepropertiespane,settheDefaultAuthorization

Providerproperty.Thisistheauthorizationproviderinstancetouseifoneisnotspecifiedinthecode.Thedefaultisnone.

9. (Optional)Inthepropertiespane,settheDefaultSecurityCacheProviderproperty.Thisisthesecuritycacheproviderinstancetouseifoneisnotspecifiedinthecode.Thedefaultisnone.

AfteryouaddtheSecurityApplicationBlocktotheapplicationconfiguration,youneedtoconfiguresomeorallofthefollowingelements:

AuthorizationRuleProviderAzManProviderCustomAuthorizationProviderSecurityCacheCustomSecurityCacheProvider

AuthorizationRuleProvider

AzManProvider




http://www.microsoft.com/downloads/details.aspx?FamilyID=e487f885-f0c7-436a-a392-25793a25bad7

http://www.microsoft.com/downloads/details.aspx?FamilyID=7edde11f-bcea-4773-a292-84525f23baf7

CustomAuthorizationProvider

SecurityCache

CustomSecurityCacheProviderToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Entering Configuration Information'%0AEntLib50_f4ab7474-104a-4203-99b8-65931a7c68e6%0APlease provide details of the error you have located...%0A


SourceSchemafortheSecurityApplicationBlock

ThistopicliststheXMLelementsandattributesusedtoconfiguretheSecurityApplicationBlock.YoucanmanuallyedittheXMLdata,buttheEnterpriseLibraryconfigurationtoolsgreatlysimplifythistask.IfyouchoosetomanuallyedittheXML,usetheschemainformationcontainedinthistopic.


<configSections>

<sectionname="securityConfiguration"

type="Microsoft.Practices.EnterpriseLibrary.Security.Configuration.SecuritySettings,

Microsoft.Practices.EnterpriseLibrary.Security"/>

</configSections>

Thesection-handlerdeclarationcontainsthenameoftheconfigurationsettingssectionandthenameofthesection-handlerclassthatprocessesconfigurationdatainthatsection.ThenameoftheconfigurationsettingssectionissecurityConfiguration.Thenameofthesection-handlerclassisMicrosoft.Practices.EnterpriseLibrary.Security.Configuration.SecuritySettings

securityConfigurationElement

authorizationProvidersChildElement

rulesChildElement

securityCacheProvidersChildelement




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Source Schema for the Security Application Block'%0AEntLib50_a109681e-bda0-4a48-a2ef-99b40881e235%0APlease provide details of the error you have located...%0A

CopyCode



TheSecurityApplicationBlockisdesignedtosupportthemostcommonscenariosforauthorizationandcachingofsecurityinformation.Whenyouaddyourapplicationcode,refertothescenariosintheKeyScenariossection,andselecttheonesthatbestmatchyoursituation.Usethecodethataccompaniesthescenarioas-isoradaptitasnecessary.

First,youmustprepareyourapplicationtousetheSecurityApplicationBlock.

Toprepareyourapplication1. AddareferencetotheSecurityApplicationBlockassembly.InVisual

Studio,right-clickyourprojectnodeinSolutionExplorer,andthenclickAddReferences.ClicktheBrowsetab,andthennavigatetothelocationoftheMicrosoft.Practices.EnterpriseLibrary.Security.dllassembly.Selecttheassembly,andthenclickOKtoaddthereference.

2. Followthesameproceduretosetareferencetothefollowingassemblies:


3. Ifyouintendtousesecuritycaching,setareferencetotheassemblyMicrosoft.Practices.EnterpriseLibrary.Security.Cache.CachingStore.dllYoualsoneedtoaddareferencetotheDataAccessApplicationBlockassembly,Microsoft.Practices.EnterpriseLibrary.Data.dll,ifyouareusingtheDatabaseCacheStoragestoreintheCachingApplicationBlock.

4. (Optional)TouseelementsfromtheSecurityApplicationBlockwithoutfullyqualifyingtheelementreference,youcanaddtheusingstatement(C#)orImportsstatement(VisualBasic)tothetopofyoursourcecodefile.ThefollowingcodeshowshowtoaddthesestatementsfortheMicrosoft.Practices.EnterpriseLibrary.Securitynamespace.C#

usingMicrosoft.Practices.EnterpriseLibrary.Security;

VisualBasic

ImportsMicrosoft.Practices.EnterpriseLibrary.Security




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Application Code'%0AEntLib50_c2eafe24-9460-4387-b3e8-1ec0862a0fb9%0APlease provide details of the error you have located...%0A


KeyScenarios

Thistopicdescribesthemostcommonsituationsdevelopersmustaddresswhenprovidingsecurityfunctionalityintheirapplications.Eachscenarioexplainsthetask,describesareal-worldsituationwheresuchataskmightoccur,andincludescodethatdemonstrateshowtousetheSecurityApplicationBlocktocompletethetask.Thescenariosarethefollowing:

ObtainingaTemporaryTokenforanAuthenticatedUser.ThisscenarioillustrateshowtousetheSaveIdentitymethodtocacheanauthenticatedidentityandreturnatemporarytokenthatservesasanalternativetousercredentialsforthedurationoftheusersession.Youcanalsousethistechniquetosaveauserprincipalorauseridentity.AuthenticatingaUserUsingaToken.ThisscenarioillustrateshowtousetheGetIdentitymethodtoreturnanidentitythathasalreadybeencached,whenprovidedwithavalidtoken.Thesametechniquecanbeusedtoretrieveauserprincipaloruserprofile.TerminatingaUserSession(ExpiringaToken).ThisscenarioillustrateshowtousetheExpireIdentitymethodtoexpireatokencorrespondingtoanidentity,whentheusersessionends.Youcanalsousethistechniquetoexpireauserprincipalorauserprofile.DeterminingWhetheraUserIsAuthorizedtoPerformaTask.ThisscenarioillustrateshowtousetheAuthorizemethodofanauthorizationprovidertoperformauthorization.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Key Scenarios'%0AEntLib50_38631da1-4370-48dd-a411-cd4109b41ccb%0APlease provide details of the error you have located...%0A


ObtainingaTemporaryTokenforanAuthenticatedUser

Anexampleofwhenyoumightwanttoobtainatemporarytokenforanauthenticateduseriswhenyouwanttoimprovetheperformanceofyourapplicationbypassingthetokeninsteadoffrequentlyauthenticatingthesameuserduringasinglesession.Youcanusetheapproachdescribedheretosaveauserprincipalorauseridentityinthesecuritycacheandobtainatokenthatrepresentstheuser'sauthenticatedidentity.

TypicalGoals

Solution

UsingSaveIdentity




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Obtaining a Temporary Token for an Authenticated User'%0AEntLib50_d38d1bbb-5b89-4a2c-b69d-9368b441e7d3%0APlease provide details of the error you have located...%0A


AuthenticatingaUserUsingaToken

Anexampleofwhenyoumightwanttouseatemporarytokenforauthenticationiswhenyouwanttoimprovetheperformanceofyourapplicationbypassingthetokeninsteadoffrequentlyauthenticatingauserduringasinglesession.Youcanusetheapproachdescribedheretoretrieveasaveduserprincipalorauseridentityfromthesecuritycacheusingatokenyoupreviouslyobtainedthatrepresentstheuser'sauthenticatedidentity.

TypicalGoals

Solution

UsingGetIdentity




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Authenticating a User Using a Token'%0AEntLib50_1982837c-1981-42b5-98ae-3c4f2bfe0093%0APlease provide details of the error you have located...%0A


TerminatingaUserSession(ExpiringaToken)

Anexampleofwhenyoumaywanttoexpireatokeniswhenyouwanttomakesurethatthetokencannotbeusedbyanattackeraftertheuserlogsout.Youcanusetheapproachdescribedheretoexpireauserprincipalorauseridentity.

TypicalGoals

Solution

UsingExpireIdentity




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Terminating a User Session (Expiring a Token)'%0AEntLib50_5c6b60a1-e93d-4bc8-b8a2-1d9d7eb292c1%0APlease provide details of the error you have located...%0A


DeterminingWhetheraUserIsAuthorizedtoPerformaTask

Acommonsecurityrequirementistheneedtoauthorizeuserstoperformtasks.TheSecurityApplicationBlockhelpsbystandardizingaccesstoauthorizationproviderssuchastheAzManAuthorizationProviderortheAuthorizationRuleProvider,ortoauthorizationrulesstoredwithintheapplicationconfiguration.

TypicalGoals

Solution

UsingAuthorize




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Determining Whether a User Is Authorized to Perform a Task'%0AEntLib50_a843fda6-3226-41c0-be10-b926563f1339%0APlease provide details of the error you have located...%0A


DesignoftheSecurityApplicationBlock

TheSecurityApplicationBlockaddressesthefollowingareas:AuthorizationSecurity-relatedcaching

DesignGoals





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Security Application Block'%0AEntLib50_aa26f732-d76d-42f4-83ee-2d0a86b625ec%0APlease provide details of the error you have located...%0A


DesigningforSimplifiedAuthorization

Uniformimplementationsmakecodeeasiertounderstand,morepredictable,andeasiertomaintain.However,developerscanimplementauthorizationinapplicationsinmanydifferentways.Forexample,theymayhavetouseanapproachthatconformstothesecuritypoliciesoftheirorganizations.Alternatively,theymayuseapproachesthatsuittheneedsofparticulardepartmentsoroftheapplicationsthemselves.

TheSecurityApplicationBlockencapsulatesthelogicthatperformsauthorizationoperationsintoasingleinterfacethatspecifiesonlyasmallnumberofmethods.Thesemethodscanbeusedbydifferentauthorizationproviders.ThismeansthatapplicationsthatusetheSecurityApplicationBlockareconsistentinthewaysthattheyauthorizeuserstoperformtasks.ByusingtheSecurityApplicationBlock,thisconsistencyremainsacrosssingleprojects,multipleprojects,orenterprise-scalesolutions.

DesignImplications




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Designing for Simplified Authorization'%0AEntLib50_27041f1c-bf13-4b55-92ee-a89bdd0f191b%0APlease provide details of the error you have located...%0A


ExtendingandModifyingtheSecurityApplicationBlock

Initsoriginalstate,theSecurityApplicationBlockworkswellfortypicalsecurityscenarios.However,theremaybetimeswhenyouhavetocustomizesomeoftheblock'sbehaviortobettersuityourapplication'sparticularrequirements.Therearetwowaystodothis.YoucanextendtheCachingApplicationBlockusingthebuilt-inextensionpoints.Youcanalsomodifytheblockbymakingchangestoitssourcecode.Formoredetails,seethefollowingtopics:

ExtendingtheSecurityApplicationBlockExtendingandModifyingEnterpriseLibrary




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying the Security Application Block'%0AEntLib50_9433d798-60e9-4f3c-8e9e-c06415c18b21%0APlease provide details of the error you have located...%0A


ExtendingtheSecurityApplicationBlock

YouextendtheSecurityApplicationBlockthroughdesignatedextensionpoints.Typically,thesearecustomclasses,writtenbyyou,thatimplementaparticularinterfaceorderivefromanabstractclass.Becausethesecustomclassesexistinyourapplicationspace,youdonothavetomodifyorrebuildtheblock.Instead,youdesignateyourextensionsusingconfigurationsettings.

YoucanextendtheblockbyaddinganewtypeofAuthorizationProviderorbyaddinganewsecuritycacheproviderthatintegrateswithyourchosencachingmechanism.Thefollowingtableliststheinterfacesandbaseclassesthatyoucanusetoextendtheblock.


AuthorizationProvider AuthorizationProvider

SecurityCacheProvider ISecurityCacheProvider


CreatinganAuthorizationProviderToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending the Security Application Block'%0AEntLib50_e513cc05-64e9-43d1-94b2-012891831399%0APlease provide details of the error you have located...%0A



Twoofanadministrator'smaintaskswillbetomakesurethattheinitialdeploymentoftheSecurityApplicationBlockisplannedandmanaged,andthatsubsequentupdatesaredeployedwithminimalimpacttoexistingapplicationsthatusetheblock.FordetailsofdeployingandupdatingEnterpriseLibraryandtheapplicationblocks,seeDeployingEnterpriseLibrary.

Inaddition,administratorsmustdecidewhethertheywanttousetheinstrumentationexposedbytheblock.Fordetailsofhowtoenableanddisableinstrumentation,seeEnablingInstrumentation.ForinformationabouttheinstrumentationcontainedwithintheSecurityApplicationBlock,seethefollowingtopics:

SecurityApplicationBlockPerformanceCountersSecurityApplicationBlockEventLogEntries




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deployment and Operations'%0AEntLib50_a19232ca-b155-48e8-9870-837eaabbc5e4%0APlease provide details of the error you have located...%0A


SecurityApplicationBlockPerformanceCounters

ThefollowingtabledescribestheSecurityApplicationBlockperformancecounters.

Performancecountername Description

AuthorizationRequestsDenied/sec

Therateatwhichauthorizationrequestsweredenied.

AuthorizationRequests/sec Therateatwhichauthorizationrequestswerereceived.

SecurityCacheReads/sec Therateatwhichsecuritycachereadswererequested.

TotalAuthorizationRequests Thetotalnumberofauthorizationrequestsreceived.

TotalAuthorizationRequestsDenied

Thetotalnumberofauthorizationrequestsdenied.

TotalSecurityCacheReads Thetotalnumberofsecuritycachereadsrequested.






mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Security Application Block Performance Counters'%0AEntLib50_12f09ff5-d6e6-44c5-a78b-4071dbbceafe%0APlease provide details of the error you have located...%0A


SecurityApplicationBlockEventLogEntries

ThistopicliststheSecurityApplicationBlockeventlogentries.Thelisteneristheclassthatraisedtheevent.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Security Application Block Event Log Entries'%0AEntLib50_f7f983de-3244-4320-9a51-f6c349dd46a8%0APlease provide details of the error you have located...%0A


TheValidationApplicationBlock

Anyapplicationthatacceptsinputeitherfromusersorfromothersystemsmustensurethattheinformationisvalidintermsofsomesetofrulesthatyouspecify.Forexample,whenprocessinganorder,youmayneedtocheckthatacustomer'sphonenumberhasthecorrectnumberofdigitsorthatadatefallswithinaparticularrange.Inaddition,ifthevalidationfails,youmayneedtosendanerrormessagethatexplainswhatiswrong.

TheEnterpriseLibraryValidationApplicationBlockprovidesusefulfeaturesthatallowdeveloperstoimplementstructuredandeasy-to-maintainvalidationscenariosintheirapplications.Inaddition,theValidationApplicationBlockincludesadaptersthatallowyoutousetheapplicationblockwiththefollowingtechnologies:

ASP.NETWindows®CommunicationFoundation(WCF)WindowsPresentationFoundation(WPF)WindowsForms

ThissectionincludesthefollowingtopicsthatwillhelpyoutounderstandandusetheValidationApplicationBlock:

WhatDoestheValidationApplicationBlockDo?Thistopicprovidesabriefoverviewthatwillhelpyoutounderstandwhattheblockcando,andexplainssomeoftheconceptsandfeaturesitincorporates.Italsoprovidesasimpleexampleofhowyoucanwritecodetousetheblock.WhenShouldIUsetheValidationApplicationBlock?Thistopicwillhelpyoutodecideiftheblockissuitableforyourrequirements.Itexplainsthebenefitsofusingtheblock,andalternativetechniquesyoumayconsider.DevelopingApplicationsUsingtheValidationApplicationBlock.ThistopicexplainshowtoincludetheValidationApplicationBlockinyourapplicationsandhowtoconfigureit.Italsocontainsmoredetailedinformation,suchashowtocreatecustommessagetemplatesandinformationonhowvalidationworkswithinheritance.KeyScenarios.ThistopicshowsdifferentwaystousetheValidationApplicationBlockinyourownapplications.

DesignoftheValidationApplicationBlock.ThistopicincludesaclassdiagramoftheValidationApplicationBlock.ExtendingandModifyingtheValidationApplicationBlock.Thistopicexplainshowtoextendtheapplicationblockbyaddingcustomvalidatorsandattributes.Italsocontainsadviceabouthowtomodifythesourcecode.DeploymentandOperations.Thistopicexplainshowtodeployandupdatetheapplicationblockassemblies.Italsoexplainstheapplicationblock'sinstrumentation.

MoreInformationForrelatedinformation,seethefollowingpatterns&practicesguides:

HowTo:ProtectFromInjectionAttacksinASP.NETSecurityPractices:ASP.NETSecurityPracticesataGlanceMicrosoftApplicationArchitectureGuide,2ndEdition



http://msdn2.microsoft.com/en-us/library/bb355989.aspx




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Validation Application Block'%0AEntLib50_aab84364-c170-478c-b0d6-fa48a662dc80%0APlease provide details of the error you have located...%0A


WhatDoestheValidationApplicationBlockDo?

Unlikemanyothervalidationmechanismsandlibraries,whichuseseparatevalidationcontrolstovalidateindividualUIelementssuchastextboxes,theValidationApplicationBlockisdesignedtoallowyoutoeasilyvalidateinstancesofobjects.Thismeansthatyoucanexecutevalidationatanypointinyourapplication,andrepeatitwhenrequired.Forexample,youcanvalidateaninstanceofaclasspopulatedwithvaluesfromtheUI,validateaninstanceoftheclasspopulatedwithvaluesreceivedfromaWebservice,andvalidateaninstanceoftheclassasitpassesbetweenlayersofyourapplication.

Theblockprovidesalibraryofclassesnamedvalidators,whichimplementfunctionalityforvalidating.NETFrameworkdatatypes.Youcanalsogroupvalidatorstogetherinaruleset.Arulesetallowsyoutovalidateacomplexobjectorgraphbycomposingdifferentvalidatorsofdifferenttypesandapplyingthemtoelementsintheobjectgraph.Examplesoftheseelementsincludefields,properties,andnestedobjects.

Youconfigurevalidationrequirementsforspecificclassesbydefiningthesetofvalidatorsandtherulestoapplywhenvalidatingparameterandpropertyvaluesforinstancesofthatclass.Then,inmanysituations,youcanvalidateaninstanceoftheclasswithasinglelineofcode.

Youcandefinevalidationrulesandcarryoutvalidationinthefollowingways:Byusingconfigurationtodefinerulesetsforspecificclasses.Theserulessetsarestoredinyourapplicationconfigurationfile,andcanbecreatedusingthegraphicalconfigurationtools.Byaddingattributestomembersofyourclassestodefineindividualrulesforpublic,readableparametersandpropertiesthatspecifyrulesetsorindividualvalidationrules.ThesemaybeattributesdefinedwithintheValidationApplicationBlockthatdirectlytargetthevalidatorsprovidedwiththeblock,or.NETDataAnnotationattributes.TheValidationApplicationBlockworkswithbothofthesetypesofattributes.Byaddingcodetoyourclassesthatperformselfvalidationoftheobjectparametersorproperties.Thisisausefulwaytoimplementverycomplexvalidationrulesthatdependontheenvironmentorexternalfactors.

Byusingcodetocreateinstancesofvalidatorsandthenexecutevalidationondemand.

Note:TheValidationApplicationBlockonlyappliesrulesspecifiedforthereturnvaluesforpublicmethodsthathavenoparameters.Tovalidateparameterswhenamethodisinvoked,ortovalidatereturnvaluesformethodsthatacceptparameters,youcanuseTheValidationHandler.Thishandlervalidatesparametervaluesbasedontherulesforeachparameter'stypeandanyvalidationattributesontheparametersthemselves.

TheValidationApplicationBlockcontainsawidevarietyofvalidators,andyoucaneasilycreatecustomvalidatorsyourselfforyourownspecificscenarios.Asexamplesofthevalidators,theblockincludesavalidatorthatchecksfornullstringsandanothervalidatorthatcheckswhetheranumberfallswithinaspecifiedrange.TherearealsospecialvalidatorsnamedtheAndCompositeValidatorandtheOrCompositeValidator.IfyoucreateanAndCompositeValidator,whichaggregatesothervalidators,allvalidatorsinthecompositevalidatormustreturntrueforsuccessfulvalidation.IfyoucreateanOrCompositeValidator,atleastoneofthevalidatorsinthecompositevalidatormustreturntrueforsuccessfulvalidation.

TheValidationApplicationBlockalsoincludesadaptorsthatyoucanuseinyourapplicationUIthatsupportthesametypeofimplementationasASP.NET,WindowsPresentationFoundation(WPF),andWindowsFormsvalidationcontrolstoprovidefeedbackandinformationtouserswhenvalidationerrorsoccur.Inaddition,theblockincludesanadapterthatmakesiteasytouseinWCFapplications.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Does the Validation Application Block Do?'%0AEntLib50_b2bd8237-b778-493f-90ff-628b7e1eb871%0APlease provide details of the error you have located...%0A


WhenShouldIUsetheValidationApplicationBlock?

YoushouldconsiderusingtheValidationApplicationBlockifyouwanttoencapsulatevalidationgoodpracticeintoeasilymaintainablecodethatyoucanreuse.Encapsulationalsoallowsyoutoseparatetheapplicationcodefromthevalidationlogic.Insomesituations,youmaybeabletoupdatethevalidationlogicwithoutredeployingtheapplication.

Inaddition,considerusingtheblockwhenyourvalidationcodemustworkacrossmultiplelayersoftheapplication'sarchitecture.Bydefiningrulesintheconfigurationforeachsegment,youcanreusethesamerulesetsinmultiplelocationswithinyourcode.

ScenariosfortheValidationApplicationBlock

BenefitsoftheValidationApplicationBlock

AlternativestotheValidationApplicationBlockToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'When Should I Use the Validation Application Block?'%0AEntLib50_1294c424-60c1-45fa-b653-fcc78e26e86d%0APlease provide details of the error you have located...%0A


DevelopingApplicationsUsingtheValidationApplicationBlock

ThissectiondescribeshowtousetheValidationApplicationBlockinyourapplications.Itexplainshowtoconfiguretheapplicationblock,andhowtoincorporatetheapplicationblockintoyourapplication.Thissectionincludesthefollowingtopics:

EnteringConfigurationInformationAddingApplicationCodeUsingtheValidationBlockValidatorsUnderstandingCommonValidatorPropertiesUnderstandingValidationResultsHowValidatorsAreCreatedValidationandInheritance





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Developing Applications Using the Validation Application Block'%0AEntLib50_53601498-09de-4686-a586-e60372630378%0APlease provide details of the error you have located...%0A



TheseproceduresexplainhowtoconfiguretheValidationApplicationBlockwiththeconfigurationtools.TheValidationApplicationBlockalsoallowsyoutouseattributesandcodetoperformmanyofthetasksdescribedhere.Forinformationabouthowtouseattributesandcode,seeUsingtheValidationBlockValidators.ForinformationaboutpropertiesthatareassociatedwithvalidatorssuchasTagandMessageTemplate,seeUnderstandingCommonValidatorProperties.

ThisprocedureexplainshowtoaddtheValidationApplicationBlocktotheconfigurationfile.FordetailsoftheschemafortheValidationApplicationBlockconfiguration,seeSourceSchemafortheValidationApplicationBlock.

ToaddtheValidationApplicationBlockbyusingtheconfigurationtool1. Opentheconfigurationfile.Formoreinformation,seeConfiguring

EnterpriseLibrary.2. OpentheBlocksmenuandthenclickAddValidationSettings.3. (Optional)Ifyouwanttoencrypttheconfigurationfile,clickthe

chevronexpanderarrowtoshowtheproperties,andthenselectaprotectionproviderfromthedrop-downlistintheProtectionProviderfield.

Thenextprocedureshowshowtodefinearulesetforthemembersofatype.ItassumesthatyouhavealreadyaddedtheValidationApplicationBlocktoyourconfiguration.Membersofatypethatyouwillvalidatecanbefields,methods,orproperties.Notethatitispossibleforatypetohavemultiplerulesetsassociatedwitheachtypeyouconfigure.Forexample,inthefollowingscreenshot,theProducttypehastworulesets,Ruleset1andRuleset2.

Ruleset1specifiesanotnullvalidatorandaregularexpressionvalidatorfortheIDproperty,andastringlengthvalidatorfortheNameproperty.Ruleset2specifiesanotnullvalidatorandastringlengthvalidatorfortheIDproperty,andarangevalidatorfortheInStockproperty.

Whenyouclickonanitemintheconfigurationtool,relateditemsarehighlightedandlinksappearbetweenthem,asshownfortheProperty:IDiteminthescreenshot.

Todefinearulesetformembersofatypebyusingtheconfigurationtool1. IfthesettingsfortheValidationSettingssectionarenotvisible,click

thechildexpanderarrowtotheleftofValidationSettings.2. ClicktheplussigniconinValidatedTypesandclickAddTypeto

Validate.3. Inthetypeselectordialogbox,expandtheassemblyyouwanttouse.

Tofilterthelist,typepartofthenameintheTypenameeditbox;forexample,type"string"tofilterforallclassescontainingtheword"string".Iftheassemblyisnotshowninthelist,clickAddfromGAC(theglobalassemblycache)orAddfromFileandnavigatetoit.SelectthetypeyouwanttovalidateandclickOK.

4. Todefinearuleset,right-clickonthetypeintheValidatedTypescolumnandthenclickAddValidationRuleset.ThisaddsarulesetwiththedefaultnameValidationRulesetandaValidatorsitemthatyoucanusetovalidatethetypeitself.

5. EdittheNamepropertyoftherulesetasrequired.6. Toaddavalidatorthatappliestoaninstanceofaclassasawhole,

ratherthantoindividualmembersofthatclass,right-clicktheValidatorsitemintheValidationTargetscolumn,pointtoAddValidators,andthenclickthevalidatoryouwanttoapply.Repeatthis

steptoaddadditionalvalidatorsthatwillbeappliedatthetypelevelifrequired.Typicallyyouwillusethisfeatureforonlyanotnullvalidator,objectcollectionvalidator,compositevalidator,oracustomvalidator.

7. Toselecttheindividualmembersofatypetobevalidated,youcanuseeitherofthefollowingmethods:

Right-clickontheheadingoftherulesetitem,andthenclickAddFieldtoValidate,AddMethodtoValidate,orAddPropertytoValidate.Thenenterthenameofthefield,method,orpropertyintheValidationTargetspane.Alternatively,youcanselectseveralmembersofatypesimultaneously.Right-clickontherulesetandclickSelectMembers.IntheMemberSelectordialogbox,selecttheProperties,Methods,and/orFieldsthatyouwanttovalidate,andthenclickOK.

8. Toaddavalidatorforatypemember,right-clicktheheadingofafield,method,orpropertyofamemberforthetypeintheValidationTargetscolumn,pointtoAddValidators,andthenclickthevalidatoryouwanttoapply.Repeatthissteptoaddadditionalvalidatorsthatwillbeappliedtoindividualtypemembersasrequired.

9. Editthepropertiesofeachvalidatoryouaddedtotheconfiguration:(Optional)EditthedefaultNameproperty.Specifythevalidationerrormessage.EntereitheraMessageTemplate(whichmayincludethevalidationmessagetokensdescribedinUnderstandingCommonValidatorProperties),orsettheTemplateResourceNameandTemplateResourceTypepropertiesifyouwanttoloadthemessagetemplatefromaresourcesfile.Tousearesourcesfile,enterthenameoftheresourcefortheTemplateResourceNamethenclickontheellipsisbutton(...)intheTemplateResourceTypepropertyandusethetypeselectortolocateandselecttheresourcesfile.(Optional)Ifyouwantthevalidatortooperateinreverse,sothatthevalidatorwillreturnfalse(failedvalidation)whenthevalidationruleissatisfied,andtrue(noerror)whenthevalidationtestfails,settheNegatedpropertytoTrue.ThedefaultisFalse.(Optional)Ifyouwanttopassanadditionaltextvaluetothe

applicationwhenvalidationfails,enterthistextastheTagproperty.Youcanfiltervalidationresultsonthevaluesyouspecifyforthisproperty.Entervaluesfortheremainingvalidatorproperties.Thepropertiesavailabledifferforeachtypeofvalidator.Foralistofpropertiesforeachtypeofvalidator,seeUsingtheValidationBlockValidators.

ThenextprocedureexplainshowtodefineanAndCompositeValidatororanOrCompositeValidator.CompositevalidatorscontainindividualvalidatorsthatarecombinedwithaBooleanANDorORoperation.Forexample,thefollowingscreenshotshowsanOrcompositevalidatorappliedtotheIDpropertyofatypeinRuleset1.ThevalidationspecifiesthateithertheruledefinedbyapropertycomparisonvalidatorortheruledefinedbyarangevalidatormustbesatisfiedforvalidationoftheIDpropertyvaluetosucceed.

Youcanalsonestcompositevalidatorstocreatecomplexlogicforamember,suchas(AOR(BANDC)).

Todefinecompositevalidators1. Right-clickthememberofthetypeyouwanttovalidate,oronthe

Validatoritemtoaddavalidatorforthetypeitself,andclickAddValidators.ThenclickeitherAddAndCompositeValidatororAddOrCompositeValidator.

2. Right-clicktheAndCompositeValidatorortheOrCompositeValidatoryouadded,pointtoAddValidatorsandthenclickoneofthevalidatorsthatwillbeapartofthecompositevalidator.Repeatthissteptoaddadditionalvalidatorsasrequired.

3. EditthepropertiesoftheAndCompositeValidatorortheOrCompositeValidator,andeditthepropertiesofeachvalidatoryouaddtothecompositevalidator:

(Optional)EditthedefaultNameproperty.

Specifythevalidationerrormessage.EntereitheraMessageTemplate(whichmayincludethevalidationmessagetokensdescribedinUnderstandingCommonValidatorProperties),orsettheTemplateResourceNameandTemplateResourceTypepropertiesifyouwanttoloadthemessagetemplatefromaresourcesfile.Tousearesourcesfile,enterthenameoftheresourcefortheTemplateResourceNamethenclickontheellipsisbutton(...)intheTemplateResourceTypepropertyandusethetypeselectortolocateandselecttheresourcesfile.(Optional)Ifyouwantthevalidatortooperateinreverse,sothatthevalidatorwillreturnfalse(failedvalidation)whenthevalidationruleissatisfied,andtrue(noerror)whenthevalidationtestfails,settheNegatedpropertytoTrue.ThedefaultisFalse.(Optional)Ifyouwanttopassanadditionaltextvaluetotheapplicationwhenvalidationfails,enterthistextastheTagproperty.Entervaluesfortheremainingvalidatorproperties.Thepropertiesavailabledifferforeachtypeofvalidator.Foralistofpropertiesforeachtypeofvalidator,seeUsingtheValidationBlockValidators.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Entering Configuration Information'%0AEntLib50_1f739afc-873e-4894-b5f5-c4cc8d902091%0APlease provide details of the error you have located...%0A


SourceSchemafortheValidationApplicationBlock

ThistopicliststheelementsandattributesusedtoconfiguretheValidationApplicationBlock.Theconfigurationfilehasthefollowingsection-handlerdeclaration:XML

<configSections>

<sectionname="validation"

type="Microsoft.Practices.EnterpriseLibrary.Validation.Configuration.ValidationSettings,

Microsoft.Practices.EnterpriseLibrary.Validation"/>

</configSections>

Thesection-handlerdeclarationcontainsthenameoftheconfigurationsettingssectionandthenameofthesection-handlerclassthatprocessesconfigurationdatainthatsection.Thenameoftheconfigurationsettingssectionisvalidation.Thenameofthesection-handlerclassisMicrosoft.Practices.EnterpriseLibrary.Validation.Configuration.ValidationSettings

validationElement

EncryptedDataElement

http://www.w3.org/TR/xmlenc-core/

typeElement

rulesetElement

fieldsElement

methodsElement

propertiesElement

validatorElementToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Source Schema for the Validation Application Block'%0AEntLib50_2e21634d-41ca-46c1-b9be-2ca5d4918de5%0APlease provide details of the error you have located...%0A



ThefollowingprocedureexplainshowtoincorporatetheValidationApplicationBlockintoyourapplication.

Toprepareyourapplication1. AddareferencetotheValidationApplicationBlockassembly.In

VisualStudio,right-clickyourprojectnodeinSolutionExplorer,andthenclickAddReference.ClicktheBrowsetabandfindthelocationoftheMicrosoft.Practices.EnterpriseLibrary.Validation.dllassembly.Selecttheassembly,andthenclickOKtoaddthereference.

2. Usethesameproceduretosetareferencetothefollowingassemblies:Microsoft.Practices.EnterpriseLibrary.Common.dllMicrosoft.Practices.ServiceLocation.dllMicrosoft.Practices.Unity.dllMicrosoft.Practices.Unity.Interception.dll

3. IfyouareusingtheASP.NET,WPF,WindowsForms,orWCFintegrationassemblies,addoneofthefollowingreferencesasappropriate.

Microsoft.Practices.EnterpriseLibrary.Validation.Integration.WinForms.dllMicrosoft.Practices.EnterpriseLibrary.Validation.Integration.AspNet.dllMicrosoft.Practices.EnterpriseLibrary.Validation.Integration.WPF.dllMicrosoft.Practices.EnterpriseLibrary.Validation.Integration.WCF.dll

4. (Optional)TouseelementsfromtheValidationApplicationBlockwithoutfullyqualifyingthetypewiththenamespace,addthefollowingusingstatements(C#)orImportsstatements(VisualBasic)tothetopofyoursourcecodefile.C#

usingMicrosoft.Practices.EnterpriseLibrary.Validation;

usingMicrosoft.Practices.EnterpriseLibrary.Validation.Validators;

VisualBasic

ImportsMicrosoft.Practices.EnterpriseLibrary.Validation

ImportsMicrosoft.Practices.EnterpriseLibrary.Validation.Validators

Note:ForVisualBasicprojects,youcanusetheReferencespageoftheProjectDesignertomanagereferencesandimportednamespaces.ToaccesstheReferencespage,selectaprojectnodeinSolutionExplorer.OntheProjectmenu,clickProperties.WhentheProjectDesignerappears,clicktheReferencestab.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Application Code'%0AEntLib50_972f39f2-7f0b-4307-be73-259c35b6d0f9%0APlease provide details of the error you have located...%0A


UsingtheValidationBlockValidators

TheValidationApplicationBlockincludesclassesnamedvalidators,whichderivefromtheValidatorclass.ThereisagenericversionofthisclassnamedValidator<T>.

Everyvalidatorisassociatedwithaspecifictype.Forexample,theStringLengthValidatorclasscheckstoseeifaSystem.Stringvaluehasalengthwithinapredefinedrange.

Therearefourwaysthatyoucanassociatevalidatorswithyourtypes:Youcanuseconfiguration.Formoreinformation,seeEnteringConfigurationInformation.Youcanuseattributes.Formoreinformation,seeUsingValidationBlockAttributesandUsingDataAnnotationAttributes.Youcanuseacombinationofconfigurationandattributes.Youcanuseselfvalidation,whichmeansthatyouincludevalidationlogicwithintheobjectyouwanttovalidate.Formoreinformation,seeUsingSelfValidation.

Youcanalsoinstantiatevalidatorswithinyourcodewithoutassociatingthemwithaspecifictype.Formoreinformation,seeCreatingValidatorsProgrammatically.

ThefollowingsectionsdescribethevalidatortypesthatareincludedwiththeValidationApplicationBlock.Thesevalidatorsarethefollowing:

AndCompositeValidatorContainsCharactersValidatorDateTimeRangeValidatorDomainValidatorEnumConversionValidatorNotNullValidatorObjectCollectionValidatorObjectValidatorOrCompositeValidatorPropertyComparisonValidatorRangeValidator

RegularExpressionValidatorRelativeDateTimeValidatorStringLengthValidatorTypeConversionValidatorSingleMemberValidators

Eachentrycontainsexamplesforhowtousethevalidatorwithattributesandwithcode.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the Validation Block Validators'%0AEntLib50_a018f049-2f2a-4383-924f-3d186dfc9ec3%0APlease provide details of the error you have located...%0A


AndCompositeValidator

ClassName:AndCompositeValidator

AttributeName:ValidatorCompositionAttribute

Configurationtoolname:AndCompositeValidator

Description

Properties

ExampleToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'And Composite Validator'%0AEntLib50_fbad360d-1f4e-48ba-b974-187cc695256d%0APlease provide details of the error you have located...%0A


ContainsCharactersValidator

ClassName:ContainsCharactersValidator

AttributeName:ContainsCharactersValidatorAttribute

Configurationtoolname:ContainsCharactersValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Contains Characters Validator'%0AEntLib50_520d5cd0-975e-4f07-87d6-4730989a5366%0APlease provide details of the error you have located...%0A


DateTimeRangeValidator

ClassName:DateTimeRangeValidator

AttributeName:DateTimeRangeValidatorAttribute

Configurationtoolname:DateTimeRangeValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Date Time Range Validator'%0AEntLib50_f6674ae4-cb64-4873-87fa-e01428cd9e4b%0APlease provide details of the error you have located...%0A


DomainValidator

ClassName:DomainValidator<T>

AttributeName:DomainValidatorAttribute

Configurationtoolname:DomainValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Domain Validator'%0AEntLib50_6d7856b6-a10b-4a1f-859c-520d314dcd2b%0APlease provide details of the error you have located...%0A


EnumConversionValidator

ClassName:EnumConversionValidator

AttributeName:EnumConversionValidatorAttribute

Configurationtoolname:EnumConversionValidator

Description

Properties

Examples




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Enum Conversion Validator'%0AEntLib50_508f15aa-7749-4cbe-a157-dfac279d6bbc%0APlease provide details of the error you have located...%0A


NotNullValidator

ClassName:NotNullValidator

AttributeName:NotNullValidatorAttribute

Configurationtoolname:NotNullValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Not Null Validator'%0AEntLib50_257e3cf3-7ba6-42c5-bdad-6cb6f1a767a5%0APlease provide details of the error you have located...%0A


ObjectCollectionValidator

ClassName:ObjectCollectionValidator

AttributeName:ObjectCollectionValidatorAttribute

Configurationtoolname:ObjectCollectionValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Object Collection Validator'%0AEntLib50_90c5c693-44a2-4929-ac36-88b31c58e6d3%0APlease provide details of the error you have located...%0A


ObjectValidator

ClassName:ObjectValidator

AttributeName:ObjectValidatorAttribute

Configurationtoolname:ObjectValidator

Description

Properties

Example

DifferencesbetweentheObjectValidatorandtheFactory-CreatedValidatorsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Object Validator'%0AEntLib50_c91d5ad6-7339-4395-bb66-ef58ad859b2c%0APlease provide details of the error you have located...%0A


OrCompositeValidator

ClassName:OrCompositeValidator

AttributeName:ValidatorCompositionAttribute

Configurationtoolname:OrCompositeValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Or Composite Validator'%0AEntLib50_69471c90-4f25-4fd4-a877-d24b39ce430b%0APlease provide details of the error you have located...%0A


PropertyComparisonValidator

ClassName:PropertyComparisonValidator

AttributeName:PropertyComparisonAttribute

Configurationtoolname:PropertyComparisonValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Property Comparison Validator'%0AEntLib50_1e57e241-3139-4dbc-bcd9-ac33c6a7a3db%0APlease provide details of the error you have located...%0A


RangeValidator

ClassName:RangeValidator<T>

AttributeName:RangeValidatorAttribute

Configurationtoolname:RangeValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Range Validator'%0AEntLib50_956d433e-e39d-41b4-940e-2af8fd35b0d6%0APlease provide details of the error you have located...%0A


RegularExpressionValidator

ClassName:RegexValidator

AttributeName:RegexValidatorAttribute

Configurationtoolname:RegularExpressionValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Regular Expression Validator'%0AEntLib50_e2d06e0b-becc-439a-94a9-eeb87f8028eb%0APlease provide details of the error you have located...%0A


RelativeDateTimeValidator

ClassName:RelativeDateTimeValidator

AttributeName:RelativeDateTimeValidatorAttribute

Configurationtoolname:RelativeDateTimeValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Relative Date Time Validator'%0AEntLib50_a4d8fef5-59a5-48f9-b7c1-035c8cef7259%0APlease provide details of the error you have located...%0A


StringLengthValidator

ClassName:StringLengthValidator

AttributeName:StringLengthValidatorAttribute

Configurationtoolname:StringLengthValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'String Length Validator'%0AEntLib50_987ea2b2-748f-462a-b04a-1fd9746ec520%0APlease provide details of the error you have located...%0A


TypeConversionValidator

ClassName:TypeConversionValidator

AttributeName:TypeConversionValidatorAttribute

Configurationtoolname:TypeConversionValidator

Description

Properties




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Type Conversion Validator'%0AEntLib50_62fff51a-7b01-4304-8ca8-b98e93c4cdb1%0APlease provide details of the error you have located...%0A


SingleMemberValidators

TheValidationApplicationBlockcontainsthreevalidatorsthatyoucanusetovalidateindividualmembersoftypes,insteadofvalidatingtheentiretypeusingattributesorrulesets.Whilenotacommonscenario,thistechniquemaybeusefulwhenintegratingwithotherframeworkssuchasWPFandWindowsForms.Thethreevalidatorsare:

FieldValueValidator.Usethisvalidatortovalidateafieldofatype.MethodReturnValueValidator.Usethisvalidatortovalidatethereturnvalueofamethodofatype.PropertyValueValidator.Usethisvalidatortovalidatethevalueofapropertyofatype.

Forexample,youcanprogrammaticallycreateavalidatorforaninstanceofaclassnamedMyClassthatvalidatesthevalueofapropertynamedMyPropertyusingaregularexpressionvalidatorasshownhere.C#

ValidatorpropValidator=newPropertyValueValidator<MyClass>("MyProperty",

newRegexValidator("some-regular-expression"));

MyClassmyInstance=newMyClass();

myInstance.MyProperty="Somevalue";

ValidationResultsresults=propValidator.Validate(myInstance);

VisualBasic

DimpropValidatorAsNewPropertyValueValidator(OfMyClass)("MyProperty",_

NewRegexValidator("some-regular-expression"))

DimmyInstanceAsNewMyClass()

myInstance.MyProperty="Somevalue"

DimresultsAsValidationResults=propValidator.Validate(myInstance)

Thatsecondparametertotheconstructoristhevalidatortouseforthepropertyvalue.Youcanalsocreateacompositevalidatorfromacombinationofvalidators,andspecifythiscompositevalidatorinthecodeabove.Asimilar

techniquecanbeusedwiththeFieldValueValidatorandMethodReturnValueValidator.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Single Member Validators'%0AEntLib50_58561dbd-2906-46e0-808c-f20a6e4b03b7%0APlease provide details of the error you have located...%0A


UnderstandingCommonValidatorProperties

ThereareanumberofpropertiesdefinedfortheValidatorclass.ThesepropertiesarealsoexposedbytheValidatorAttributeclass,whichmeansthattheycanbeusedwithanyattributethatderivesfromthisclass.

Thesepropertiesarethefollowing:MessageTemplate.Formoredetails,seeUsingtheMessageTemplateProperty.MessageTemplateResourceNameandMessageTemplateResourceType.Formoredetails,seeUsingtheMessageTemplateResources.Negate.Formoredetails,seeUsingtheNegateProperty.Tag.Formoredetails,seeUsingtheTagProperty.Ruleset.Formoredetails,seeUsingtheRulesetProperty.

UsingtheMessageTemplateProperty

UsingtheMessageTemplateResources

UnderstandingMessageTemplateTokens

http://msdn2.microsoft.com/en-us/library/system.string.format.aspx

UsingtheNegateProperty

UsingtheTagProperty

UsingtheRulesetPropertyToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Understanding Common Validator Properties'%0AEntLib50_b0eadaf4-a85e-4cae-8b18-a0f4b4403629%0APlease provide details of the error you have located...%0A


UnderstandingValidationResults

TheValidationResultstypeisacollectionofValidationResultobjects.EachValidationResultobjectcontainsareportthatincludesreferencestotheValidatorinstance,theobjectthatwasvalidated,anderrormessages.

ThefollowingtableliststhepropertiesandmethodsoftheValidationResultscollectionclass.

Member Description

AddAllResults TakesacollectionofValidationResultinstancesandaddsthemtoanexistingValidationResultsinstance.

AddResult CreatesanewValidationResultinstanceandaddsittoanexistingValidationResultsinstance.

Count ReturnsthenumberofValidationResultinstancesinthecollection.

FindAll FiltersaValidationResultsinstanceandeliminatesresultsthatdonotmatchthevalueoftheTagpropertythatwasspecifiedforthevalidator.ThismethodreturnsanewValidationResultsobjectthatcontainstherequiredsetofValidationResultinstancesandleavestheoriginalValidationResultsinstanceunchanged.

IsValid Thispropertyreturnstrueifvalidationsucceededorfalseifvalidationfailed.

ThefollowingtableliststhepropertiesoftheValidationResultclass.


Key Thisisanamethatdescribesthelocationofthevalidationresult.Itcontainsthenameofthememberthatisassociatedwiththevalidator.Itisnullifthevalidatorisdefinedatthetypelevel.

NestedVlidationResults Thenestedvalidationresultsforacomposite

failedvalidation.

Message Thisisamessagethatdescribesthevalidationfailure.

Tag ThisisavaluesuppliedbytheuserastheTagpropertyofthevalidator.Typically,itisusedforcategorizationorfiltering.Thetagcanbesuppliedthroughtheconstructorbutitistypicallyseteitherbyusingapropertyinthevalidationattributesorwithconfiguration.

Target Thisistheobjecttowhichthevalidationrulewasapplied.

Validator Thisisthevalidatorthatperformedthevalidation.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Understanding Validation Results'%0AEntLib50_94056593-c3ff-4335-85e2-db7366bdf646%0APlease provide details of the error you have located...%0A


HowValidatorsAreCreated

Whentheapplicationblockcreatesavalidator,itusesasetofrequirementstodeterminewhichtypesandmembersofthosetypescanbeassociatedwiththatvalidator.(Memberscanbemethods,properties,andfields.)

Ingeneral,whentheapplicationblockcreatesavalidator,itevaluatestheassociatedtypeanditsmembers.Onlymembersthathavethefollowingcharacteristicscanbeassociatedwithavalidator:

Theymustbepublicmembers.Methodsmustbenon-voidandtakenoparameters.Propertiesmustbereadable.

Selfvalidationhasadifferentsetofrequirements.Theyarethefollowing:Selfvalidationappliesonlytomethods.Aselfvalidationmethodcanbenon-public.Themethodsignaturemustbevoid[method](ValidationResults).Selfvalidationcanapplytoinheritedmethodsbutnottomethodsthatareprivateandinherited.

CreatingValidatorswithConfiguration

CreatingValidatorswithAttributesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'How Validators Are Created'%0AEntLib50_88136f06-f91b-4776-87ba-b17cc7f47cf1%0APlease provide details of the error you have located...%0A

CopyCode


ValidationandInheritance

Ifyouuseinheritance,youneedtoknowhowthevalidationrulesareappliedthroughouttheclasshierarchy.Hereisanexampleofasimplehierarchy,whereclassPreferredCustomerinheritsfromclassCustomer.(Thevalidatorattributesusedintheexample,suchasCustomerNameValidatorrefertocustomvalidatorsandarenotvalidatorsincludedwiththeValidationApplicationBlock.)C#

publicclassCustomer

{

[CustomerNameValidator]

publicstringName

{

get{...}

set{...}

}

[DiscountValidator]

publicvirtualdoubleDiscount

{

get{...}

set{...}

}

}

publicclassPreferredCustomer:Customer

{

[PreferredDiscountValidator]

publicoverridedoubleDiscount

{

get{...}

set{...}

}

}

VisualBasic

PublicClassCustomer

<CustomerNameValidator()>_

PublicPropertyName(ByVal_nameAsString)

Get

'...

EndGet

Set(ByValvalue)

'...

EndSet

EndProperty

<DiscountValidator()>_

PublicOverridablePropertyDiscount(ByVal_discountAsDouble)

Get

'...

EndGet

Set(ByValvalue)

'...

EndSet

EndProperty

EndClass

PublicClassPreferredCustomer

InheritsCustomer

<PreferredDiscountValidator()>_

OverridesPublicPropertyDiscount(ByVal_discountAsDouble)

Get

'...

EndGet

Set(ByValvalue)

'...

EndSet

EndProperty

EndClass

Inthisexample,thePreferredCustomerclassderivesfromtheCustomerclass,anditalsooverridestheDiscountproperty.

Therearetworulesforhowvalidatorsworkwithinaclasshierarchy:Ifaderivedclassinheritsamemberanddoesnotoverrideit,themember'svalidatorsfromthebaseclassapplytothederivedclass.Ifaderivedclassinheritsamemberbutoverridesit,themember'sattributesfromthebaseclassdonotapplytothederivedclass.

Inthisexample,theCustomerNameValidatorattributeappliestothePreferredCustomerclass,buttheDiscountValidatorattributedoesnot.Instead,thePreferredDiscountValidatorattributeapplies.

Ifthisisnotthedesiredbehavior,youcanusevalidatorsofbaseclassestocheckinstancesofderivedclasses.Thefollowingcodeexampleshowshowtodothis.ItassumesthatyouhaveresolvedaninstanceoftheValidationApplicationBlockValidatorFactoryclassandstoreditinavariablenamedvalFactory.C#

Validator<Customer>customerValidator=valFactory.CreateValidator<Customer>();

PreferredCustomermyPreferredCustomer=newPreferredCustomer();

//SetpropertiesofPreferredCustomerhere

ValidationResultsr=customerValidator.Validate(myPreferredCustomer);

VisualBasic

DimcustomerValidatorAsValidator(OfCustomer)=valFactory.CreateValidator(OfCustomer)()

DimmyPreferredCustomerAsPreferredCustomer=NewPreferredCustomer()

'SetpropertiesofPreferredCustomerhere

DimrAsValidationResults=customerValidator.Validate(myPreferredCustomer)

ThisexamplevalidatesaPreferredCustomerobject.However,thevalidationisbasedontheattributesoftheCustomerbaseclass.Thevalidationrulesdefined

onthePreferredCustomerclassarenotapplied.

YoucanusetheCreateValidator(Type)overloadoftheValidatorFactoryclasstocreateavalidatorthatisspecifictoaclassthatyouprovideatruntime.C#

publicValidationResultsCheckObject(objectobj)

{

if(obj!=null)

{

Validatorv=valFactory.CreateValidator(obj.GetType());

returnv.Validate(obj);

}

else

{

returnnull;

}

}

VisualBasic

PublicFunctionValidationResults(ByValobjAsObject)

IfNotobjIsNothingThen

DimvAsValidator=valFactory.CreateValidator(obj.GetType())

Returnv.Validate(obj)

Else

ReturnNothing

EndIf

EndFunction

ThisexamplecreatesavalidatorbasedontheruntimetypeoftheinputargumenttotheCheckObjectmethod.



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Validation and Inheritance'%0AEntLib50_62e026bd-11aa-4b03-b7e0-74c60a17f8eb%0APlease provide details of the error you have located...%0A



KeyScenarios

ThissectiondescribesthemostcommonsituationsdevelopersmustaddresswhenusingtheValidationApplicationBlock.Thefollowingscenariosareincluded:

ValidatingObjectsCreatingValidatorsProgrammaticallyUsingValidationBlockAttributesUsingDataAnnotationAttributesDefiningAttributesinMetadataClassesUsingSelfValidationIntegratingwithASP.NET,WPF,WindowsForms,andWCF




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Key Scenarios'%0AEntLib50_63ee45e2-4476-4ba9-9f31-ea108f69c755%0APlease provide details of the error you have located...%0A


ValidatingObjects

Youcanvalidateanobjectonceyouhaveobtainedareferencetoavalidationfactoryandattachedthevalidatorsandtherulesets.TheeasiestwaytoobtainareferencetoavalidationfactoryisthroughtheEnterpriseLibrarycontainer,asdescribedinCreatingandReferencingEnterpriseLibraryObjects.Thistopicdemonstratesthefollowingtechniques:

CreatingValidatorInstancesSpecifyingtheLocationofValidationRulesValidatinganObjectValidatingObjectsUsingRuleSets

Note:InpreviousreleasesofEnterpriseLibrary,youcouldusethestaticValidationfacadetovalidateobjectswithoutfirstcreatingavalidator.YoucouldalsousethestaticValidationFactoryclass(asopposedtothereplacementnon-staticValidatorFactoryclass)tocreatevalidatorinstances.Theseapproachesaresupportedinthisreleaseforbackwardscompatibilitywithexistingapplicationcode.However,totakeadvantageofbenefitsavailablewhenusingdependencyinjection,youshouldusethetechniquesdescribedinthissection.Forinformationaboutusingthestaticfacades,seetheEnterpriseLibrarydocumentationonMSDN.


CreatingValidatorInstances

SpecifyingtheLocationofValidationRules

ValidatinganObject

ValidatingObjectsUsingRuleSetsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Validating Objects'%0AEntLib50_4b3ee87e-84f6-492b-9c91-4f79686dfcdc%0APlease provide details of the error you have located...%0A


CreatingValidatorsProgrammatically

Usingattributestocreaterulesetsisonlypossibleifyouhavethesourcecodefortheclassthatyouwanttovalidate.Insomecases,thismaynotbethecase.Anotherteam,orautilitysuchastheWebServicesDescriptionLanguageTool(Wsdl.exe),maycreatetheclass—andyouhaveonlythebinaryassembly.

Inaddition,youmaywanttovalidateindividualvalues,ratherthanentireobjects.Forbothofthesescenarios,youcancreatevalidatorsprogrammatically.Thisisshowninthefollowingcodeexample.C#

Validator<string>emailAddressValidator

=newRegexValidator(@"\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*");

ValidationResultsr=emailAddressValidator.Validate(myEmailAddress);

ValidatorshortStringValidator

=newAndCompositeValidator(newNotNullValidator(),newStringLengthValidator(1,5));

shortStringValidator.Validate(myStringValue,r);

VisualBasic

DimemailAddressValidatorAsValidator(OfString)_

=NewRegexValidator("\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*")

DimrAsValidationResults=emailAddressValidator.Validate(myEmailAddress)

DimshortStringValidatorAsValidator_

=NewAndCompositeValidator(NewNotNullValidator(),NewStringLengthValidator(1,5))

shortStringValidator.Validate(myStringValue,r)

Inthisexample,thefirstlineusesnewtocreateaninstanceoftheRegExValidatorclasswiththeparametervaluesettothe@"\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*"regularexpressionstring.ThevariableemailAddressValidatorcontainsthereferencetothisinstance.ThesecondlineusesnewtocreateaninstanceoftheAndCompositeValidator

class.ThevariableshortStringValidatorcontainsthereferencetothisinstance.YoucanusetheAndCompositeValidatorclasstocreateacompositevalidator.Inthisexample,thecompositevalidatorcontainsaNotNullValidatorinstanceandaStringLengthValidatorinstance.

AfteryouprogrammaticallycreateaValidatorobject,youcanusetheValidatemethodtovalidateanobjectasdescribedinthetopicValidatingObjects.NoticehowthesecondcalltotheValidatemethodusestheoverloadthatacceptsanexistinginstanceoftheValidationResultsclassandaddsanyvalidationerrorsitfindstothelist.

Asanalternativetocreatingvalidatorsbyexecutingtheconstructor,youcanresolveindividualvalidatorsthroughtheEnterpriseLibraryContainer.Ifyouspecifyanamewhenyouresolvetheinstance,thisisinterpretedasthenameoftherulesetforthatvalidatortousewhenvalidatingobjects.YoumustaddtheValidationBlockExtensiontothecontainertousethisapproach.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Validators Programmatically'%0AEntLib50_c29ba824-b735-45ee-a5bc-26b97d13b7fc%0APlease provide details of the error you have located...%0A


UsingValidationBlockAttributes

Validationattributes(boththebuilt-inValidationApplicationBlockattributesandthosedescribedinthetopicUsingDataAnnotationAttributes)canbeusedwithvarioustargetsthatincludeclasses,fields,properties,methods,and(inlimitedcases)parameters.Forinformation,seeValidationAttributeTargets.Thereisalsoasetofattributesthatallowyoutochangethebehaviorofotherattributes.ThesearediscussedinValidationModifierAttributes.Youcanalsospecifytheattributesyouwanttouseinaseparatemetadataclass.Formoredetailsofthis,seeDefiningAttributesinMetadataClasses.

UsingValidationBlockAttributestoDefineValidationRuleSets

ValidationAttributeTargets

ValidationModifierAttributesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Validation Block Attributes'%0AEntLib50_af182675-ba7f-4721-8f3c-22e0b519a22e%0APlease provide details of the error you have located...%0A


UsingDataAnnotationAttributes

TheSystem.ComponentModel.DataAnnotationsnamespaceinthe.NETFrameworkcontainsaseriesofattributesthatyoucanaddtoyourclassesandclassmemberstosignifymetadatafortheseclassesandmembers.Theyincludearangeofvalidationattributesthatyoucanusetoapplyvalidationrulestoyourclasses,inmuchthesamewayasyoucanwiththeValidationblockattributes.Forexample,thefollowingshowshowyoucanusetheRangeattributetospecifythatthevalueofthepropertynamedOnOrdermustbebetween0and50.C#

[Range(0,50,ErrorMessage="Quantityonordermustbebetween0and50.")]

publicintOnOrder{get;set;}

VisualBasic

<Range(0,50,ErrorMessage:="Quantityonordermustbebetween0and50.")>_

PublicPropertyOnOrder()AsInteger

...

EndProperty

ComparedtothevalidationattributesprovidedwiththeValidationblock,therearesomelimitationswhenusingthevalidationattributesfromtheDataAnnotationsnamespace:

Therangeofsupportedvalidationoperationsislesscomprehensive,thoughtherearesomenewvalidationtypesavailableinversion4.0ofthe.NETFrameworkthatextendtherange.However,somevalidationoperationssuchaspropertyvaluecomparison,enumerationmembershipchecking,andrelativedateandtimecomparisonarenotavailablewhenusingdataannotationvalidationattributes.ThereisnocapabilitytouseOrcomposition,asthereiswiththeOrcompositevalidatorintheValidationApplicationBlock.Theonlycompositionavailablewithdataannotationvalidationattributesisthe

Andoperation.Youcannotspecifyrulesetsnames,andsoallrulesimplementedwithdataannotationvalidationattributesbelongtothedefaultruleset.Youwillseemoredetailsaboutrulesetslaterinthischapter.Thereisnosimplebuilt-insupportself-validation,asthereisintheValidationblock.

Note:DataAnnotationvalidatorscanonlybeappliedtoproperties.

Youcan,ofcourse,includebothdataannotationandValidationblockattributesinthesameclassifyouwish,andimplementSelfvalidationusingtheValidationblockmechanisminaclassthatcontainsdataannotationvalidationattributes.ThevalidationmethodsintheValidationblockwillprocessbothtypesofattributes.

Formoreinformationaboutdataannotations,seeSystem.ComponentModel.DataAnnotationsNamespace(.NETFrameworkversion3.5)andSystem.ComponentModel.DataAnnotationsNamespace(.NETFrameworkversion4.0).



http://msdn.microsoft.com/en-us/library/system.componentmodel.dataannotations.aspx

http://msdn.microsoft.com/en-us/library/system.componentmodel.dataannotations(VS.100).aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Data Annotation Attributes'%0AEntLib50_7c70f9ca-e5a4-4089-9f59-6fc5adae16ef%0APlease provide details of the error you have located...%0A


DefiningAttributesinMetadataClasses

Insomecases,youmaywanttolocateyourvalidationattributes(bothValidationblockattributesand.NETDataAnnotationvalidationattributes)inaseparatefiletotheonethatdefinestheclassthatyouwillvalidate.Thisisacommonscenariowhenyouareusingtoolsthatgeneratetheclassfiles,andwouldthereforeoverwriteyourvalidationattributes.Toavoidthisyoucanlocateyourvalidationattributesinaseparatefilethatformsapartialclassalongwiththemainclassfile.ThisapproachmakesuseoftheMetadataTypeattributefromtheSystem.ComponentModel.DataAnnotationsnamespace.

YouapplytheMetadataTypeattributetoyourmainclassfile,specifyingthetypeoftheclassthatstoresthevalidationattributesyouwanttoapplytoyourmainclassmembers.Youmustdefinethisaspartialclass,asshownhere.Theonlychangetothecontentofthisclasscomparedtotheattributedversionsyousawintheprevioussectionsofthischapteristhatitcontainsnovalidationattributes.C#

[MetadataType(typeof(ProductMetadata))]

publicpartialclassProduct

{

...Existingmembersdefinedhere,butwithoutattributesorannotations...

}

VisualBasic

<MetadataType(GetType(ProductMetadata))>_

PartialPublicClassProduct

...Existingmembersdefinedhere,butwithoutattributesorannotations...

EndClass

Youthendefinethemetadatatypeasanormalclass,exceptthatyoudeclaresimplepropertiesforeachofthememberstowhichyouwanttoapplyvalidationattributes.Theactualtypeofthesepropertiesisnotimportant,andis

ignoredbythecompiler.TheacceptedapproachistodeclarethemallasoftypeObject.Asanexample,ifyourProductclasscontainstheIDandDescriptionproperties,youcandefinethemetadataclassforitasshownhere.C#

publicclassProductMetadata

{

[Required(ErrorMessage="IDisrequired.")]

[RegularExpression("[A-Z]{2}[0-9]{4}",

ErrorMessage="ProductIDmustbe2capitallettersand4numbers.")]

publicobjectID;

[StringLength(100,ErrorMessage="Descriptionmustbelessthan100chars.")]

publicobjectDescription;

}

VisualBasic

PublicClassProductMetadata

<Required(ErrorMessage:="IDisrequired.")>_

<RegularExpression("[A-Z]{2}[0-9]{4}",_

ErrorMessage:="ProductIDmustbe2capitallettersand4numbers.")>_

PublicIDAsObject

<StringLength(100,ErrorMessage:="Descriptionmustbelessthan100chars.")>_

PublicDescriptionAsObject

EndClass

Formoreinformation,seeMetadataTypeAttributeClassonMSDN.



http://msdn.microsoft.com/en-us/library/system.componentmodel.dataannotations.metadatatypeattribute.aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Defining Attributes in Metadata Classes'%0AEntLib50_39033729-17d6-45e5-bb55-9f787641ae02%0APlease provide details of the error you have located...%0A


UsingSelfValidation

Selfvalidationallowsyoutoimplementvalidationlogicwithintheclassyouwanttovalidate.UsetheHasSelfValidationattributetomarktheclassthatcontainsthevalidationlogic.UsetheSelfValidationattributetomarkeachSelfvalidationmethodwithinthatclass.Thefollowingcodeexampleshowshowtodothis.C#

usingMicrosoft.Practices.EnterpriseLibrary.Common.Configuration;



[HasSelfValidation]

publicclassTemperatureRange

{

privateintmin;

privateintmax;

//...

[SelfValidation]

publicvoidCheckTemperature(ValidationResultsresults)

{

if(max<min)

results.AddResult(newValidationResult("Maxlessthanmin",this,"","",null));

}

}

VisualBasic

ImportsMicrosoft.Practices.EnterpriseLibrary.Common.Configuration



CopyCode

CopyCode

<HasSelfValidation()>_

PublicClassTemperatureRange

PrivateminAsInteger

PrivatemaxAsInteger

'...

<SelfValidation()>_

SubCheckTemperature(ByValresultsAsValidationResults)

Ifmax<minThen

results.AddResult(NewValidationResult("Maxlessthanmin",Me,"","",Nothing))

EndIf

EndSub

EndClass

Inthisexample,theCheckTemperaturemethodprovidesselfvalidation.WhentheValidation.ValidatemethodiscalledonaninstanceofTemperatureRange,theCheckTemperaturemethodisinvoked.

IfyoudonotspecifyarulesetnameintheSelfValidationattribute,theselfvalidationroutineispartofthedefaultruleset.Tospecifyarulesetname,includetheRulesetparameterintheSelfValidationattributeasshownbelow.YoucanincludemorethanoneSelfValidationmethodinaclassanddifferentiatethemusingrulesetnames.C#

[SelfValidation(Ruleset="SimpleRuleset")]

publicvoidValidate(ValidationResultsresults)

{

...

}

VisualBasic

<SelfValidation(Ruleset:="SimpleRuleset")>_

PublicSubValidate(resultsAsValidationResults)

...

EndSub

EachSelfvalidationmethodmusthaveavoidreturnvalueandtakeaValidationResultsinstanceasitsonlyparameter.TheSelfvalidationmethodshouldupdatetheValidationResultsinstanceafterperformingthevalidationifthevalidationfails.FormoreinformationabouttheValidationResultsclass,seeUnderstandingValidationResults.

IfyouhaveaderivedclassandyouwantittoinherittheSelfvalidationbehaviorofitsbaseclass,youmustmarkboththebaseclassandthederivedclasswiththeHasSelfValidationattribute.TheSelfvalidationmethodsinthebaseclassmustbepublicinorderforthemtobeincludedintheselfvalidationofthederivedclass.

Selfvalidationworksincombinationwithanyvalidatorsthatareassignedtoaclass.Therefore,theValidationResultsforanobjectinstancewillincludeboththeresultsfromtheselfvalidationaswellastheresultsfromvalidatorswithintheclass.Inthefollowingcodeexample,theAddressclassusesself-validation,andthestringZipCodehastheStringLengthValidatorassigned.C#




[HasSelfValidation]

publicclassAddress

{

privatestring_zipCode;

[StringLengthValidator(1,10,MessageTemplate="ZipCodeInvalidLength")]

publicstringZipCode

{

get{return_zipCode;}

set{_zipCode=value;}

}

[SelfValidation]

publicvoidDoValidate(ValidationResultsresults)

{

ValidationResultresult=newValidationResult("ErrorMessage",typeof(Address),"","",null);

ValidationResultresult2=newValidationResult("ErrorMessage2",typeof(Address),"","",null);

results.AddResult(result);

results.AddResult(result2);

}

}

VisualBasic




<HasSelfValidation()>_

PublicClassAddress

Private_zipCodeAsString

<StringLengthValidator(1,10,MessageTemplate:="ZipCodeInvalidLength")>_

PublicPropertyZipCode()AsString

Get

Return_zipCode

EndGet

Set(ByValvalueAsString)

_zipCode=value

EndSet

EndProperty

<SelfValidation()>_

SubDoValidate(ByValresultsAsValidationResults)

DimresultAsNewValidationResult("ErrorMessage",GetType(Address),"","",Nothing)

Dimresult2AsNewValidationResult("ErrorMessage2",GetType(Address),"","",Nothing)

results.AddResult(result)

results.AddResult(result2)

EndSub

EndClass




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Self Validation'%0AEntLib50_949240d5-f9c7-4779-a8fd-19e0912a6a74%0APlease provide details of the error you have located...%0A


IntegratingwithASP.NET,WPF,WindowsForms,andWCF

Integrationallowsyoureusethevalidatorsthatareassociatedwithyourapplicationclasseswhenyouperformvalidationattheuser-interfacelevel(forASP.NET,WPF,andWindowsFormsapplications)oratthemessage-sendinglevelofamulti-tieredapplication(forWCFapplications).ByintegratingtheValidationApplicationBlockwithyourapplications,youcanreuseyourvalidationrulesacrossseverallevelsofyoursystemarchitecture.

TheintegrationprovidedbytheValidationApplicationBlockattheuser-interfaceleveldoesthefollowing:

Itprovidesawaytoassociatepropertiesofvalidatedapplicationobjectswithuser-interfacecontrols.Itprovidesawaytoconvertvaluesfromaninputdatatypetoanapplication-specificdatatype.Forexample,youcanconvertastringinputtoaSystem.DateTimevalue.Ithelpsavoidcodingerrorsintypenamesandpropertynames.Forexample,itthrowsexceptionswhentypenamesorpropertynamescannotbefound.Itdoesnotrequireinstancesofapplicationobjectstobecreatedinorderforvalidatorstobeinvokedattheuser-interfacelevel.Inotherwords,youdonotneedtoinstantiateaCustomerobjectjusttocheckwhetheraninputstringenteredbytheusermeetsthevalidationrequirementsoftheCustomer.Nameproperty.

TheintegrationprovidedbytheValidationApplicationBlockforthemessage-passinglevelallowsyoutovalidateWCFmessages,datacontracts,andparameters.

TheValidationApplicationBlockisdesignedtointegratewitharangeofpresentationtechnologies.Fordetails,seetheflowingtopics:

IntegratingwithASP.NETIntegratingwithWPFIntegratingwithWindowsFormsIntegratingwithWCF

Toprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.


Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Integrating with ASP.NET, WPF, Windows Forms, and WCF'%0AEntLib50_8d3c2b6c-46e8-4d1f-8297-bff4131187e2%0APlease provide details of the error you have located...%0A

CopyCode


IntegratingwithASP.NET

YoucanintegratetheValidationApplicationBlockwithASP.NETapplications.Forexample,youcanusetheapplicationblocktovalidateinformationauserentersintoaWebform.ASP.NETisintegratedwiththeValidationApplicationBlockthroughthetypesdefinedintheMicrosoft.Practices.EnterpriseLibrary.Validation.Integration.AspNetassembly.

ThePropertyProxyValidatorclassdefinedinthisassemblyprovidesthemainintegrationpoint.ItspurposeistocheckanASP.NETcontrol'svalueusingthevalidatorsthatareincludedinauser-providedapplicationclass.ThePropertyProxyValidatorclassactsasawrapperthatlinksacontroltoavalidatorinanapplication-levelclass.

ThePropertyProxyValidatorclassraisestheValueConverteventwhenitneedstoconvertthetypeofavalueenteredintotheassociatededitcontrol.Youcanhandlethiseventtoprovideacustomtypeconverterforconvertingvaluesenteredbytheusertovaluesrequiredbythevalidators.Ifyoudonotspecifyahandler,adefaultconversionisperformedbytheASP.NETTypeConverterservices.

TousethePropertyProxyValidatorcontrol,youmustmanuallyaddthecodetoan.aspxfile,asshowninthefollowingexample.

<cc1:propertyproxyvalidator

id="firstNameValidator"

runat="server"

ControlToValidate="firstNameTextBox"

PropertyName="FirstName"

RulesetName="RuleSetA"

SourceTypeName="BusinessEntities.Customer">

</cc1:propertyproxyvalidator>

TheSourceTypeNameattributeshowninthedesigner-generatedsource

referencestheCustomerclassdefinedelsewhereintheapplication.Thisistheclasswhosevalidatorswillbeused.

WhenusingASP.NETwiththeValidationApplicationBlock,youmayneedtoconvertdatatypessuchasdatesbeforeyoucanvalidatethedata.Theintegrationlibraryprovidesawayforyoutoinsertcodethatperformsthisconversion.Todothis,youneedtoprovideaneventhandlerfortheconversionandthenreferencethishandlerinthe.aspxfile.Thefollowingcodeexcerptshowsahandlerthatconvertsadateofbirthstringintoadate.C#




usingMicrosoft.Practices.EnterpriseLibrary.Validation.Integration;

usingMicrosoft.Practices.EnterpriseLibrary.Validation.Integration.AspNet;

protectedvoiddateOfBirthValidator_ValueConvert(objectsender,ValueConvertEventArgse)

{

stringvalue=e.ValueToConvertasstring;

try

{

e.ConvertedValue=DateTime.Parse(value,System.Globalization.CultureInfo.CurrentCulture);

}

catch

{

e.ConversionErrorMessage="DateOfBirthisnotinthecorrectformat.";

e.ConvertedValue=null;

}

}

VisualBasic




ImportsMicrosoft.Practices.EnterpriseLibrary.Validation.Integration

ImportsMicrosoft.Practices.EnterpriseLibrary.Validation.Integration.AspNet

ProtectedSubdateOfBirthValidator_ValueConvert(ByValsenderAsObject,ByValeAsValueConvertEventArgs)_

HandlesdateOfBirthValidator.ValueConvert

DimstringValueAsString=CStr(e.ValueToConvert)

DimdateValueAsDateTime

DimsuccessAsBoolean=DateTime.TryParse(stringValue,dateValue)

IfsuccessThen

e.ConvertedValue=dateValue

Else

e.ConversionErrorMessage="DateOfBirthisnotinthecorrectformat."

e.ConvertedValue=Nothing

EndIf

EndSub

ThefollowingcodeshowsthedateOfBirthTextBoxcontrolandthedateOfBirthValidatorinanASP.NETpage.TheOnValueConvertattributeofthePropertyProxyValidatorspecifiesthenameoftheeventhandlershowninthepreviouscode,andislocatedintheassociatedASP.NETcode-behindfile.

<asp:TextBoxID="dateOfBirthTextBox"runat="server"/>

<cc1:PropertyProxyValidatorID="dateOfBirthValidator"runat="server"

ControlToValidate="dateOfBirthTextBox"

PropertyName="DateOfBirth"

RulesetName="RuleSetA"

SourceTypeName="Customer"

OnValueConvert="dateOfBirthValidator_ValueConvert">

</cc1:PropertyProxyValidator>




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Integrating with ASP.NET'%0AEntLib50_58e249cd-6d83-4d55-9773-dcd6f081b2cf%0APlease provide details of the error you have located...%0A


IntegratingwithWPF

YoucanintegratetheValidationApplicationBlockwithWindowsPresentationFoundation(WPF)applications.Forexample,youcanusetheapplicationblocktovalidatethevaluesinUIcontrolsinaccordancewithrulesdefinedforboundpropertiesofanobject.ValidationisperformedaspartofthegeneralBindingmechanism.ForinformationabouttheWPFbindingmechanism,seeDataBindingOverviewonMSDN.Thevalidationrulesyouspecifycanbeconfiguredtovalidateatdifferentstagesinthebindingprocessingpipeline.Forinformationaboutapplyingvalidationrules,seeHowto:ImplementBindingValidationandValidationStepEnumerationonMSDN.

Note:TheValidationApplicationBlockcannotbeusedinXMLBrowserApplications(XBAP)duetoissueswiththepartialtrustenvironmentthatXBAPmandates.

TousetheWPFintegrationfeature,youmustaddareferencetotheassemblyMicrosoft.Practices.EnterpriseLibrary.Validation.Integration.WPF.TheintegrationisperformedthroughacustomValidationRulenamedValidatorRuledefinedinthisassembly,whichperformsitsvalidationbyinvokingtheValidationApplicationBlockvalidatorforaspecificpropertyonagiventype.Validationonlyoccursifabindingexists,andthatbindingisconnected(ifthesourceofthebindingexists).

Youcanaddavalidationruledirectlytoabindingbyspecifyingthedesiredtypeandpropertynames,asshownhere.XAML

<TextBoxx:Name="TextBox1">

<TextBox.Text>

<BindingPath="ValidatedStringProperty"UpdateSourceTrigger="PropertyChanged">

<Binding.ValidationRules>

<vab:ValidatorRule



http://msdn.microsoft.com/en-us/library/system.windows.controls.validationstep.aspx

SourceType="{x:Typetest:ValidatedObject}"

SourcePropertyName="ValidatedStringProperty"/>

</Binding.ValidationRules>

</Binding>

</TextBox.Text>

</TextBox>

YoucanalsosettheRulesetNameandValidationSpecificationSourcepropertiestorefinehowthevalidatorforthespecifiedpropertyiscreated.

IfthevalueofthevalidatedcontrolthatcarriestheRequiredvalidationattributeisemptytobeginwith,andremainsemptyduringvalidation,thesourceisnotupdatedandvalidationdoesnotoccur.InthisparticularcasetheValidateOnTargetUpdatepropertywillnotworkeitherbecausethenulldefaultvalueofthetargetwillnotchange.Instead,youcaninvokeUpdateSourceonthebindingtoforcevalidationtooccur,asshownhere.C#

this.Required.GetBindingExpression(TextBox.TextProperty).UpdateSource();

VisualBasic

Me.Required.GetBindingExpression(TextBox.TextProperty).UpdateSource()

ThevalidationruleoperatesintheConvertedProposedValuestep,afterthevaluehasbeenconvertedbutbeforeitissetonthesource.Thismeansthatvalueconversionerrorsmustbedetectedthroughothermechanism.OneapproachistoenabletheValidatesOnDataErrorspropertyonthevalidatedbinding.

ConfiguringValidationthroughAttachedPropertiesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Integrating with WPF'%0AEntLib50_8279cff2-91a2-4af7-ac5a-928e1bc64a3e%0APlease provide details of the error you have located...%0A


IntegratingwithWindowsForms

YoucanintegratetheValidationApplicationBlockwithWindowsFormsapplications.Forexample,youcanusetheapplicationblocktovalidateinformationauserentersintoaWindowsForm.WindowsFormsisintegratedwiththeValidationApplicationBlockthroughthetypesdefinedintheMicrosoft.Practices.EnterpriseLibrary.Validation.Integration.WinFormsassembly.

TheValidationProviderclassdefinedinthisassemblyprovidesthemainintegrationpoint.ThisclassisanextenderproviderthataddspropertiestoWindowsFormscontrols.ThisproviderallowsyoutospecifyhowtousetheValidationApplicationBlocktovalidatethecontrols'values.

YoucanperformvalidationautomaticallybyusingtheControl.ValidatingeventoryoucaninitiateitinyourcodebyinvokingtheValidationProvider.PerformValidation(Control)method.Inbothcases,youmustusethevalidationprovidertoconfigurethecontrol.

YoucanalsospecifyaninstanceoftheErrorProviderclassforthecontrol.Ifyoudothis,thevalidationerrorsthatresultifthevalidationfailsaresenttotheerrorproviderasaproperlyformattederrormessage.

TheValidationProvider.Enabledpropertyenablesanddisablesthevalidationprovider.Whenitisdisablednovalidationoccurs,thevalidationproviderisconsideredvalid,andanyerrormessagespostedtotheErrorProviderarecleared.Whenitisre-enabled,theprovidercontinuestobevalidanddoesnotpostanyerrormessagesuntilvalidationistriggeredagain.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Integrating with Windows Forms'%0AEntLib50_a37f938a-f41d-4ad5-acd5-ae1871f84239%0APlease provide details of the error you have located...%0A


IntegratingwithWCF

WindowsCommunicationFoundation(WCF)providesextensionpointsthatallowyoutosupportcustomscenariossuchascheckingsecurityattributesandperformingpolicyassertions.TheValidationApplicationBlockincludesaWCFintegrationlibrarythataddsacustombehavior,andaparameterinspector.ThisextensionallowstheapplicationblocktovalidateWCFmessages,datacontracts,andparameters.

WhentheWCFservicebegins,itinvokesthecustombehavior.Thiscustombehaviorthenaddstheparameterinspector.WCFcallstheparameterinspectortwiceforeachmessageitprocesses.Thefirsttimeisbeforeitsendsthecalltotheserviceimplementation.Thesecondtimeisaftertheservicegeneratesthereturnmessage.ThissectionexplainshowyoucanusetheValidationApplicationBlockwithyourWCFapplications.Ingeneral,youmustdothefollowing:

IncludetheValidationApplicationBlockinyourservicecontract.Defineabehaviorthatusestheapplicationblock.Defineanendpointthatusesthebehavior.Modifytheservicecontractsothattheclientcanreceiverelevantfailureinformation.Addvalidatorstoparametersasrequired.

IncludingtheValidationApplicationBlock

DefiningaBehavior

DefininganEndpoint

ReportingValidationFaults

ValidatingParametersToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Integrating with WCF'%0AEntLib50_bd65d946-ec7a-4e8d-844f-b9e3285bf224%0APlease provide details of the error you have located...%0A


DesignoftheValidationApplicationBlock

TheValidationApplicationBlockisdesignedtodothefollowing:Encapsulatethelogicusedtoperformthemostcommonvalidationtasksintominimalapplicationcode.Relievedevelopersoftherequirementtowriteduplicatecodeandcustomcodeforcommonvalidationtasks.Allowvalidationrulestobechangedaftertheapplicationhasbeendeployed,andensurethatchangeshappensimultaneouslyandconsistently.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of the Validation Application Block'%0AEntLib50_063a2fba-d573-4928-aaab-8611e5c50b91%0APlease provide details of the error you have located...%0A


ExtendingandModifyingtheValidationApplicationBlock

Initsoriginalstate,theValidationApplicationBlockworkswellfortypicalvalidationscenarios,suchasvalidatingdataforanASP.NETapplication.However,theremaybetimeswhenyouhavetocustomizecertainbehaviorsoftheapplicationblocktobettersuityourapplication'sparticularrequirements.Therearetwowaystodothis.YoucanextendtheValidationApplicationBlockusingthebuilt-inextensionpoints.Youcanalsomodifytheapplicationblockbymakingchangestoitssourcecode.Formoredetails,seethefollowingtopics:

ExtendingtheValidationApplicationBlockExtendingandModifyingEnterpriseLibrary




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying the Validation Application Block'%0AEntLib50_a68e1e80-6a81-4d65-ac1f-d8b0d1ad602a%0APlease provide details of the error you have located...%0A


ExtendingtheValidationApplicationBlock

YouextendtheValidationApplicationBlockthroughdesignatedextensionpoints.Typically,thesearecustomclasseswrittenbyyouthatimplementaparticularinterfaceorderivefromanabstractclass.Becausethesecustomclassesexistinyourapplicationspace,youdonothavetomodifyorrebuildtheValidationApplicationBlock;instead,youcandesignateyourextensionsthroughconfigurationsettings.

YoucanextendtheValidationApplicationBlockbyimplementingnewvalidators.YoucancreateyourownValidatorclassesandyourownattributesiftheonesprovidedwiththeValidationApplicationBlockdonotfityourrequirements.Theseclassescouldvalidatedatatypesinnewwaysortheycoulddealwithmorecomplexdatatypes,suchasaCustomerdatatypethatincludesmanydifferentdatatypes.

Thefollowingtableliststhebaseclassesthatyoucanusetoextendtheblock.

CustomProviderorExtension BaseClass

Validator Validator<T>orValidator

ValidatorAttribute ValueValidatorAttribute

YoucanextendtheValidator<T>baseclasstocreatestronglytypedvalidators.YoucanusetheValidatorbaseclasstocreatelooselytypedvalidators.





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending the Validation Application Block'%0AEntLib50_491dae6e-3c21-4ec1-900b-74098bb9cffe%0APlease provide details of the error you have located...%0A



Twoofanadministrator'smaintaskswillbetoseethattheinitialdeploymentoftheValidationApplicationBlockisplannedandmanagedandthatsubsequentupdatesaredeployedwithminimalimpacttoexistingapplicationsthatusetheapplicationblock.FordetailsofdeployingandupdatingEnterpriseLibraryandtheapplicationblocks,seeDeployingEnterpriseLibrary.

Inaddition,administratorsmustdecidewhethertheywanttousetheinstrumentationexposedbytheapplicationblock.Fordetailsofhowtoenableanddisableinstrumentation,seeEnablingInstrumentation.ForinformationabouttheinstrumentationcontainedwithintheValidationApplicationBlock,seethefollowingtopics:

ValidationApplicationBlockPerformanceCountersValidationApplicationBlockEventLogEntries




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deployment and Operations'%0AEntLib50_13938ec0-548a-4e42-850d-01e1672cbec2%0APlease provide details of the error you have located...%0A


ValidationApplicationBlockPerformanceCounters

ThefollowingtableliststheValidationApplicationBlockperformancecountersandtheirtypes.

PerformanceCounter CounterType

%ValidationSuccesses RawFraction

NumberofValidationCalls NumberOfItems32

NumberofValidationFailures NumberOfItems32

NumberofValidationSuccesses NumberOfItems32

ValidationCalls/sec RateOfCountsPerSecond32

ValidationFailures/sec RateOfCountsPerSecond32

ValidationSuccessesBase RawBase

ValidationSuccesses/sec RateOfCountsPerSecond32

TheseperformancecountersareintheEnterpriseLibraryValidationCounterscategory.Eachperformancecounterhastwoinstances:

AppDomain-Total,whereTotalisallofthetypesthatarevalidatedwithintheapplicationdomain.AppDomain-TypeName,whereTypeNameisthenameofthetypebeingvalidated.

Formoreinformationaboutperformancecounters,seeOverviewofPerformanceMonitoringinthe.NETFrameworkClassLibraryonTechNet.





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Validation Application Block Performance Counters'%0AEntLib50_87060073-b797-43c5-a367-28e736622d0d%0APlease provide details of the error you have located...%0A


ValidationApplicationBlockEventLogEntries

TheValidationApplicationBlockisinstrumentedtologentriestotheapplicationeventlogifavalidationfails.ThefailureisattributedtoEnterpriseLibraryValidationanditisdescribedasanError.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Validation Application Block Event Log Entries'%0AEntLib50_b8b67b0c-059f-4d0b-8fbb-29903023f5ce%0APlease provide details of the error you have located...%0A


UnityDependencyInjectionandInterception

WelcometoUnity.ThefollowingsectionsofthisguidancedescribethewaysthatyoucanuseUnitydependencyinjectionandUnityinterceptioninyourapplications.Thesectionsare:

WhatIsUnity?WhatDoesUnityDo?WhenShouldIUseUnity?AboutThisReleaseofUnityConfiguringUnity

UsingUnityinApplicationsDesignofUnityExtendingandModifyingUnityDeploymentandOperationsUnityQuickStarts.ThistopicwalksthroughtheQuickStartapplicationsthatdemonstratehowtoexecutecommonoperationsinyourapplications.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Unity Dependency Injection and Interception'%0AEntLib50_16137689-c8fb-46b0-87f5-7f975241832f%0APlease provide details of the error you have located...%0A


WhatIsUnity?

Unityisalightweight,extensibledependencyinjectioncontainerthatsupportsinterception,constructorinjection,propertyinjection,andmethodcallinjection.YoucanuseUnityinavarietyofdifferentwaystohelpdecouplethecomponentsofyourapplications,tomaximizecoherenceincomponents,andtosimplifydesign,implementation,testing,andadministrationoftheseapplications.

Unityisageneral-purposecontainerforuseinanytypeofMicrosoft®.NETFramework-basedapplication.Itprovidesallofthefeaturescommonlyfoundindependencyinjectionmechanisms,includingmethodstoregistertypemappingsandobjectinstances,resolveobjects,manageobjectlifetimes,andinjectdependentobjectsintotheparametersofconstructorsandmethodsandasthevalueofpropertiesofobjectsitresolves.

Inaddition,Unityisextensible.Youcanwritecontainerextensionsthatchangethebehaviorofthecontainer,oraddnewcapabilities.Forexample,theinterceptionfeatureprovidedbyUnity,whichyoucanusetoaddpoliciestoobjects,isimplementedasacontainerextension.

ThefollowingsectionsofthisguidancedescribewhatUnitycando,whenyoushouldchooseUnity,andthewaysthatyoucanuseitinyourapplications:

WhatDoesUnityDo?ThistopicprovidesabriefoverviewthatwillhelpyoutounderstandwhatUnitycando,andexplainssomeoftheconceptsandfeaturesitincorporates.ItalsoprovidesasimpleexampleofthewaythatyoucanwritecodetouseUnity.WhenShouldIUseUnity?ThistopicwillhelpyoutodecideifUnityissuitableforyourrequirements.ItexplainsthebenefitsofusingUnity,andanyalternativetechniquesyoumayconsider.ItalsoprovidesdetailsofanylimitationsofUnitythatmayaffectyourdecisiontouseit.AboutThisReleaseofUnity.Thistopiccontainsinformationaboutthechangesinthisrelease,thetargetaudienceandsystemrequirements,migrationandside-by-sideexecution,andlinkstootherMicrosoftpatterns&practicesresources.ConfiguringUnity.ThistopicdescribeshowyoucanpopulateaUnitycontainerwiththetyperegistrations,mappings,extensions,andother

informationrequiredbyyourapplication.UsingUnityinApplications.ThistopicexplainshowtouseUnityinyourownapplications.ItexplainshowtoaddUnitytoyourapplication,howtoresolveobjects,andhowtotakeadvantageofthemanyothercapabilitiesofUnity.DesignofUnity.ThistopicexplainsthedecisionsthatwentintodesigningUnityandtherationalebehindthosedecisions.ExtendingandModifyingUnity.ThistopicexplainshowtoextendUnityandhowtomodifythesourcecode.DeploymentandOperations.ThistopicexplainshowtodeployandupdatetheUnityassembliesandusetheinstrumentationexposedbyUnity.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Is Unity?'%0AEntLib50_4a39f9d3-4d76-4f71-8eb0-d171a9619c4e%0APlease provide details of the error you have located...%0A


WhatDoesUnityDo?

Byusingdependencyinjectionframeworksandinversionofcontrolmechanisms,youcangenerateandassembleinstancesofcustomclassesandobjectsthatcancontaindependentobjectinstancesandsettings.ThefollowingsectionsexplainthewaysthatyoucanuseUnity,andthefeaturesitprovides:

TheTypesofObjectsUnityCanCreateRegisteringExistingTypesandObjectInstancesManagingtheLifetimeofObjectsSpecifyingValuesforInjectionPopulatingandInjectingArrays,IncludingGenericArraysInterceptingCallstoObjects

TheTypesofObjectsUnityCanCreate

RegisteringExistingTypesandObjectInstances

ManagingtheLifetimeofObjects

ConfiguringTypesforInjectionintoConstructors,Methods,andProperties

PopulatingandInjectingArrays,IncludingGenericArrays

InterceptingCallstoObjects




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'What Does Unity Do?'%0AEntLib50_7dcce5cc-4513-4205-a020-4d1522257d91%0APlease provide details of the error you have located...%0A


WhenShouldIUseUnity?

Dependencyinjectionprovidesopportunitiestosimplifycode,abstractdependenciesbetweenobjects,andautomaticallygeneratedependentobjectinstances.Ingeneral,youshoulduseUnitywhen:

Youwishtobuildyourapplicationaccordingtosoundobjectorientedprinciples(followingthefiveprinciplesofclassdesign,orSOLID),butdoingsowouldresultinlargeamountsofdifficult-to-maintaincodetoconnectobjectstogether.Yourobjectsandclassesmayhavedependenciesonotherobjectsorclasses.Yourdependenciesarecomplexorrequireabstraction.Youwanttotakeadvantageofconstructor,method,orpropertycallinjectionfeatures.Youwanttomanagethelifetimeofobjectinstances.Youwanttobeabletoconfigureandchangedependenciesatruntime.Youwanttointerceptcallstomethodsorpropertiestogenerateapolicychainorpipelinecontaininghandlersthatimplementcrosscuttingtasks.YouwanttobeabletocacheorpersistthedependenciesacrosspostbacksinaWebapplication.

ThefollowingsectionsprovidemoreinformationtohelpyoudecidewhetherUnityissuitableforyourrequirements:

ScenariosforUnityBenefitsofUnityLimitationsofUnity

Note:EnterpriseLibrary,alsofromtheMicrosoftpatterns&practicesgroup,usesUnityasitsprimarymechanismforgeneratinginstancesofEnterpriseLibraryobjects.ForinformationaboutthisandotherfeaturesofEnterpriseLibrary,seetheEnterpriseLibraryCommunitysiteonCodePlex,ortheMicrosoftEnterpriseLibrarypagesonMSDN®.



ScenariosforUnity

BenefitsofUnity

LimitationsofUnityToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'When Should I Use Unity?'%0AEntLib50_d6246175-9719-4e2c-a636-1ad4dfc37e98%0APlease provide details of the error you have located...%0A


AboutThisReleaseofUnity

ThissectioncontainsthefollowingtopicsthatwillhelpyoutounderstandthisreleaseofUnityandhelpyouunderstandhowtouseitalongsideearlierversionsormigrateyourapplicationstothisversion.Thissectionincludesthefollowingtopics:

ChangesinThisReleaseTargetAudienceandSystemRequirementsMigrationandSide-by-SideExecutionRelatedpatterns&practicesLinksCopyrightandTermsofUse

HowtoUseThisGuidance





http://msdn.microsoft.com/en-us/magazine/cc337885.aspx







mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'About This Release of Unity'%0AEntLib50_1443c48a-8487-4e61-883b-05bc40b0db87%0APlease provide details of the error you have located...%0A


ChangesinThisRelease

Unity2.0–April2010isanewreleaseoftheMicrosoftpatterns&practicesUnitydependencyinjectionandinterceptionsystem.Thisreleasealsoincludesadditionsinfunctionality,andhasbeenadaptedtoworkwithMicrosoftVisualStudio®2010;andwiththeMicrosoft.NETFrameworkversions3.5SP1and4.0.

GotoCodePlexforinformationonKnownIssues.

ThefollowingsectionsdiscussthechangestoUnity:

BreakingChangestoUnity

ChangesinUnity


BreakingChangestoUnity

ChangesinUnityToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Changes in This Release'%0AEntLib50_d3c06077-2924-4fa0-bde8-3276f28c5859%0APlease provide details of the error you have located...%0A


TargetAudienceandSystemRequirements

Thisguidanceisintendedforsoftwarearchitectsandsoftwaredevelopers.Togetthegreatestbenefitfromthisguidance,youshouldhaveanunderstandingofthefollowingtechnologies:

MicrosoftVisualC#®orMicrosoftVisualBasic.NETMicrosoft.NETFramework

SystemRequirementsandPrerequisites

SystemRequirementsforUnityforSilverlightToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Target Audience and System Requirements'%0AEntLib50_c678b828-6309-41e9-bc24-04c290d448bb%0APlease provide details of the error you have located...%0A


MigrationandSide-by-SideExecution

Ingeneral,applicationsthatusepreviousversionsofUnitywillfunctionwiththisreleasewithouttheneedforanycodechanges.Itwillbenecessary,however,toupdatethereferencestorefertothenewassembliesandtoupdatetheconfigurationfilestoreferencethecorrectversionoftheassemblies.

ThisversionofUnitycanalsobeinstalledsidebysidewithearlierversions.YoucandeploynewapplicationswrittenforthisversionofUnityalongwithapplicationswrittenforearlierversions.Inaddition,youcanalsochoosetomigrateexistingapplicationstothenewversion.

Ifyoudecidetouseside-by-sideexecution,youmustdeploythedifferentUnityversionsindifferentdirectories.Inanyspecificdirectory,youcannotmixandmatchassembliesfromdifferentversions.

TheshippedprojectfilesusedataintheAssemblyInfo.csfiletobuildassembliesthathavedifferentversioninformation.Thisallowsyoutousestrongnamesandtoadddifferentversionstotheglobalassemblycache(GAC)forside-by-sideexecution.

PartialMigrationToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Migration and Side-by-Side Execution'%0AEntLib50_e6057c7c-8fb1-4474-8a4a-3216a08f6980%0APlease provide details of the error you have located...%0A


ReusingConfigurationFilesBasedonaPreviousSchema

AlthoughthisdocumentationisbasedontheUnity2.0configurationschemaandallexamplesuseUnity2.0,partialbackwardcompatibilityisprovidedfortheUnity1.2configurationschema.However,youcannotsimplyuseaUnity1.2configurationfile.InordertousethecontentsofaUnity1.2configurationfileyoumust:

1. Createanewconfigurationfile.2. Editthe<configSections>topointtothecorrectassembly.3. Adda<sectionExtension>sectionifyouareusingcontainer

extensionsforUnity.4. CutandpastetheportionsoftheUnity1.2configurationfileyouwish

toreuse.Note:

Checktheresultsasyoustillmaygeterrorsdependinguponthespecificportionsyoucutandpaste.

ForinformationonusingtheUnity1.2configurationschemaseeUnityConfigurationSchematiconMSDN®.


MigratingCustomExtensionsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Reusing Configuration Files Based on a Previous Schema'%0AEntLib50_31182987-ac03-4ebd-94bd-8c00e87c2948%0APlease provide details of the error you have located...%0A


Relatedpatterns&practicesLinks

ForinformationrelatedtoUnityandothertools,andguidancefordesigningandbuildingapplications,seethepatterns&practiceswebsiteandguides:

Microsoftpatterns&practicesDeveloperCenterMicrosoftApplicationArchitectureGuide,2ndEditionSolutionDevelopmentFundamentalsSecurityGuidanceforApplicationsIndex.NETDataAccessArchitectureGuideImproving.NETApplicationPerformanceandScalabilityMonitoringin.NETDistributedApplicationDesignDeploying.NETFramework-basedApplications







http://msdn.microsoft.com/en-us/library/ee817654(v=MSDN.10).aspx





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Related patterns & practices Links'%0AEntLib50_8c366d7f-d13d-4b0a-9714-ebef804d19ea%0APlease provide details of the error you have located...%0A


CopyrightandTermsofUse

Thisdocumentisprovided"as-is".Informationandviewsexpressedinthisdocument,includingURLandotherInternetwebsitereferences,maychangewithoutnotice.Youbeartheriskofusingit.

Someexamplesdepictedhereinareprovidedforillustrationonlyandarefictitious.Norealassociationorconnectionisintendedorshouldbeinferred.

ThisdocumentdoesnotprovideyouwithanylegalrightstoanyintellectualpropertyinanyMicrosoftproduct.Youmaycopyandusethisdocumentforyourinternal,referencepurposes.

©2010Microsoft.Allrightsreserved.

Microsoft,Windows,WindowsServer,WindowsVista,VisualC#,VisualBasic,andVisualStudioaretrademarksoftheMicrosoftgroupofcompanies.Allothertrademarksarepropertyoftheirrespectiveowners.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Copyright and Terms of Use'%0AEntLib50_7aaacbb6-adda-470d-bbe1-242c84a52f8c%0APlease provide details of the error you have located...%0A


ConfiguringUnity

OneofthekeytasksyouneedtoperformwhenusingUnityistoconfigurethecontainerwiththerequiredaliases,typeregistrations,mappings,andotherinformationthatitrequiresinordertoresolveobjectsatruntimeandinjecttheappropriateobjectsandvaluesintodependentobjects.ThissectioncoversalloftheconfigurationoptionsforUnity,anddescribeshowyoucanconfigurethecontainerusingaconfigurationfile,oratruntimeusingcode.

UnitycanreadconfigurationinformationfromanXMLconfigurationfile.Bydefault,thisistheApp.configorWeb.configfileforyourapplication.However,youcanloadconfigurationinformationfromanyotherXMLformatfileorfromothersourcesifrequired.

Inaddition,Unityexposesaseriesofmethodsthatyouuseinyourapplicationcodetoconfigurethecontainer.Thisapproachisusefulwhentheregistrationsandmappingsdependontheenvironmentorrun-timeinformation,andyoucanchangetheconfigurationatruntimeusingthesemethods.Run-timeconfigurationisalsoagoodchoiceifyouwanttobeabletomanipulatecontainerhierarchiesatruntimetochangetheoverallbehavioroftyperesolution,injection,andinterception.

Youcan,ofcourse,useacombinationofdesign-time(configurationfiles)andrun-timeconfigurationtoachieveexactlytheconfigurationyourequireatanypointduringapplicationexecution.

TohelpyouunderstandhowtoconfigureUnity,thissectiondividestheinformationintotwoseparatesubsections—onefordesign-timeconfigurationandoneforrun-timeconfiguration.Eachsectioncontainsbasicallythesamesetoftopicsthatdescribespecificconfigurationscenarios.

Note:Theconfigurationfilesarenotencryptedbydefault.Aconfigurationfilemaycontainsensitiveinformationaboutconnectionstrings,userIDs,passwords,databaseservers,andcatalogs.Youshouldprotectthisinformationagainstunauthorizedread/writeoperationsbyusingencryptiontechniques.Ifyouwishtorestrictaccesstotheconfigurationfile,itmustbeencryptedor

protectedusingAccessControlLists.Itisrecommendedthattheconfigurationstoreisinthesametrustboundaryandthatdecryptingtheconfigurationisdoneinthesametrustboundaryaftertheconfigurationisread.

Thecompletesetoftopicsinthissectionisasfollows:Design-TimeConfiguration

UsingtheConfigurationToolUsingDesign-TimeConfigurationSpecifyingTypesintheConfigurationFileSpecifyingValuesforInjectionExtendingtheUnityConfigurationSchemaConfigurationFilesforInterceptionDefaultAliasesandAssemblies

Run-TimeConfigurationUsingRunTimeConfigurationRegisteringTypesandTypeMappingsCreatingInstanceRegistrationsRegisteringInjectedParameterandPropertyValuesRegisteringGenericParametersandTypesRegisteringContainerExtensionsRegisteringInterception

Forinformationaboutusingcontainerhierarchies,seeUsingContainerHierarchies.ForinformationaboutusingUnity,seeUsingUnityinApplications.





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring Unity'%0AEntLib50_62fd666c-08c5-424a-b484-9e0b87994997%0APlease provide details of the error you have located...%0A


Design-TimeConfiguration

ThistopicdescribesthetechniquesyoucanusetoconfigureUnitycontainersusingaconfigurationfileoraconfigurationyouloadintothecontaineratruntime.

Note:ThisdocumentationisbasedontheUnity2.0configurationschemaandallexamplesuseUnity2.0.PartialbackwardcompatibilityisprovidedfortheUnity1.2configurationschema.

ThefollowingtopicsdescribeUnityconfiguration:UsingtheConfigurationTool.NotavailableforUnityconfiguration.UsingtheUnityXSDtoEnableVisualStudioIntelliSense.ThistopicexplainshowtousetheUnityXSDtoenableIntelliSense®inVisualStudiotoassistinmanuallyeditingtheUnityconfiguration.ReusingConfigurationFilesBasedonaPreviousSchema.ThistopicexplainshowtocreateacurrentconfigurationfilebyreusingaconfigurationfilebasedonapreviousUnityschema.UsingDesign-TimeConfiguration.ThistopicexplainstheoverallstructureoftheUnityconfigurationfile,howyouloadconfigurationinformationatruntime,andhowyoucanusealternativeconfigurationsourceswithUnity.SpecifyingTypesintheConfigurationFile.Thistopicexplainshowtoconfiguremappingsinthecontainerbetweentypes.Ingeneral,youwillcreatemappingsbetweenaninterfaceandatypethatimplementstheinterface,orbetweenabaseclassandatypethatinheritsthatbaseclass.YoucanalsousethissectiontospecifyconcretetypesforwhichyouwantUnitytomanagethelifetime.TheUnityConfigurationSchema.ThistopicdescribestheconfigurationschemaelementsforUnity.SpecifyingValuesforInjection.Thistopicexplainshowtoconfigureregistrationsforinstancetypessuchasstring,dateandtime,orinteger

valuesthatyoucanresolveinyourapplication.ExtendingtheUnityConfigurationSchema.ThistopicexplainshowtoconfigureUnitytoloadandusecontainerextensionsthataddadditionalfunctionalitytothecontainer,andhowyoucanspecifyconfigurationinformationfortheseextensions.ConfigurationFilesforInterception.Thistopicexplainshowtoconfigureinterceptors,behaviors,policies,handlers,andmatchingrulesthatUnitywillusewhencreatinginstancesoftypestowhichyouwanttoaddinterceptioncapabilitiesinordertochangethebehaviorofthatobjectortype.

ForinformationabouthowtoconfigureUnityusingcodethatexecutesatruntimeandcallstheregistrationmethodsoftheUnitycontainer,seeRun-TimeConfiguration.Forinformationaboutresolvingtypesatruntime,seeResolvingObjects.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design-Time Configuration'%0AEntLib50_d084d31d-6894-4cd3-ab6b-40f7a69899b2%0APlease provide details of the error you have located...%0A


UsingtheConfigurationTool

NotavailableforUnityconfiguration.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the Configuration Tool'%0AEntLib50_c1996f16-1bd5-4f6b-b400-6d206cee9a1f%0APlease provide details of the error you have located...%0A


UsingtheUnityXSDtoEnableVisualStudioIntelliSense

YoucanenableIntelliSenseinVisualStudiotoassistthemanualeditingofUnityconfigurationfiles.

Note:TheXSDisnotrequired.Configurationwillworkatruntimewithoutit.ItisonlyrequiredforIntelliSenseinVisualStudio.

InorderfortheXSDtobeusedbytheVisualStudioeditorthe<unity>elementmusthaveanXMLNSattributewiththecorrectnamespace.Thefollowingarethetwowaystogetthecorrectnamespaceinsteadofmanuallyenteringit:

YoucanforcetheeditortousetheschemabyclickingSchemasontheXMLmenuandselectingtheentryfortheunityconfigurationschema.Afterthat,the<unity>elementwillappearasanalternativeintheIntelliSensedropdownandbychoosingitfromIntelliSensethexmlnsattributewillbepopulated.Thisisaper-userandper-projectsetting,soeveryuserworkingontheprojectwouldberequiredtoselectthissetting.Youcanenter<unityxmlns="andthenIntelliSensewillshowalistofnamespaceswhicharetargetedbyaknownschema.Youcanthenchoosetherightnamespace,http://schemas.microsoft.com/practices/2010/unity,whichwillshowupintheIntelliSenselistwhenyouclickonthexmlnsattributeandcompletetheentry.VisualStudiowillthenassociatetheURLwiththeactualphysicalfile.Thisistherecommendedoption,sincethesettingpersistswhenyoupasstheconfigurationfiletoanotheruser.

Collectionelements,suchasaliases,containers,extensions,namespaces,andassembliesarenotsupportedbythexsd,buttheydoworkintheconfigurationfile.

Therearesomepre-definedtypenamesforsometypeattributes,suchasforlifetimemanagers,butthesearejustsuggestionsandanytypenameisaccepted.

Theschemafortheregisterelementimposesaspecificorderforitschildren,an

orderthatisnotrequiredbytheconfigurationruntimebutmakestheschemamorerobust.Theorderofchildrenisasfollows:oneoptionallifetime,oneoptionalconstructor,andthenasmanyofmethod,property,interceptor,interceptionBehavior,addInterfaceandanycustomelementasdesired,inanyorder.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using the Unity XSD to Enable Visual Studio IntelliSense'%0AEntLib50_6291a046-272b-47e5-97a1-836dca7da77e%0APlease provide details of the error you have located...%0A


UsingDesign-TimeConfiguration

UsingUnitytypicallyrequirestheconfigurationofaDependencyInjection(DI)container.YoucanconfigureacontainerbyusingtheUnityAPI,a.NETconfigurationfile,ortoalimiteddegreebyusingattributes.ThistopicdescribeshowtouseanXMLconfigurationfiletosupplytherequiredconfigurationinformation..

Dependencyinjectionisaveryflexiblepattern,andtobeusedsuccessfullyrequiresthedevelopertoprovideinformationtothecontainerabouthisapplications.Thetwomostcommonconfigurationtasksaresettinguptypemappingsandconfiguringinjectionofatype.Typemappingsenableyoutorequestatypefromthecontainerthatresultsinthecontainerreturninganinstanceofadifferenttype(typicallyaderivedclassorinterfaceimplementation).Configuringinjectionforatypeentailsspecifyinginformationsuchaswhichconstructorgetscalled,whichpropertiesgetinjected,andwhattheirvaluesare.TheUnityconfigurationschemaencompassesthesetypesofconfigurationandisalsoextensibletoallowforadditionalkindsofconfigurationsuchasUnityinterceptionconfiguration,seeTheUnityConfigurationSchema.Thefollowingsectionsprovidemoredetails:

FormatoftheUnityConfigurationFileLoadingConfigurationFileInformationintoaContainerLoadingtheConfigurationfromAlternativeFiles

FormatoftheUnityConfigurationFile

LoadingConfigurationFileInformationintoaContainer



http://msdn.microsoft.com/en-us/library/system.configuration.configurationmanager.openmappedexeconfiguration.aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Design-Time Configuration'%0AEntLib50_032275ef-ab31-4d95-84b2-6c39a79f80a2%0APlease provide details of the error you have located...%0A


SpecifyingTypesintheConfigurationFile

ThistopicexplainshowtousetypesinUnityconfigurationfiles.AtthecoreofUnity'sfunctionalityaretypesandhowyouspecifyandhandlethem.Youwillneedtospecifytypesmanytimesinthetypicalconfigurationfile.Theconfigurationfileshavetheirownsetofrulesforwritingtypenames—rulesthatdifferfromthosefortypeswritteninC#orVisualBasic.TheserulesapplyeverywhereyoucanspecifyatypeintheUnityconfigurationsection.

Thistopiccontainsthefollowingsectionthatdescribehowyoucanspecifytypes:

CLRTypeNamesTypeAliasesAutomaticTypeLookupDefaultAliasesandAssembliesGenericTypes

CopyCode

CopyCode

CLRTypeNamesYoucanspecifyatypenamebyusingtheCLRstandardtypenamesyntax,asshowninthefollowingexample:

<namespace>.<typename>,<assembly>

Youcanuseeitherpartialassemblynamesorfullyqualifiedassemblynameswhichincludetheculture,version,andpublickeytoken.Thesenamesarestraightforwardforsimpletypes.

Inordertospecifyanameforatypethatisintheglobalassemblycache,youmustusethefullyqualifiedassemblynameforthetypetobecorrectlyloaded.Forexample,forSystem.String,atypeinmscorlib,youcannotuseSystem.String,mscorlib.Youmustusethefullyqualifiedassemblyname,System.String,mscorlib,Version=2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089.

CLRtypenamescanbeveryverbose,especiallywhenworkingwithgenerictypes.Forexample,comparethefollowingsimpledictionaryinC#orVisualBasicwiththeCLRexample:C#

Dictionary<string,int>

VisualBasic

Dictionary(OfString,Integer)

CLR

System.Collections.Generic.Dictionary`2[[System.String,mscorlib,2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089],[System.Int32,mscorlib,Version=2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089]],mscorlib,Version=2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089

Inordertoexpeditetheprocessandmaketypenameslesserrorprone,Unityconfigurationprovidestwooptionsyoucanuseintheconfigurationfile:aliasesandautomatictypelookup.

TypeAliasesAnaliasissimplyashorthandnamethatwillbereplacedwiththefulltypenamewhenconfigurationisappliedtothecontainer.Youspecifyanaliasintheconfigurationfileinsidethesection,butoutsideany<container>elements,asshowninthefollowingexample:XML

<unityxmlns="http://schemas.microsoft.com/practices/2010/unity">

<aliasalias="MyAlias"type="fulltypename"/>

...

</unity>

Therearethefollowingrulesforusingaliases:Youcanhaveanarbitrarynumberof<alias>elementsintheconfigurationfile.Anywhereyoucangiveatypenameyoucanuseanaliasinstead.Therearenorecursivealiases,whichmeansthatyoucannotuseanaliastodefinethetypeforanalias.Aliasnamesarecasesensitive:<aliasalias="int"/>and<aliasalias="Int"/>aretwodifferentaliasesandarenotinterchangeable.

Note:Aliasesonlyexistatconfigurationtime.Theyarenotavailableatruntime.

AutomaticTypeLookupInmanycases,likeforILoggerintheFormatoftheUnityConfigurationFileexample,thenameofatypeisallthatisrequired.ButgivenUnity'sdependenceontypesandthelargenumberoftypestypicallyinvolvedinaconfiguration,theabilitytoperformautomatictypelookupsfurtherexpeditestheprocess.Byincorporatingautomatictypelookups,Unityalsoeliminatestheneedtodefineanaliasforeverytypeinanassembly,whichsaveseffortandservestoreducethechanceforerrorfromrepeatedlytypingthenamespaceandassemblyname.

TheUnityconfigurationsystemcansearchfortypes.However,itwillonlylookfortypesifthetypenamespecifiedisnotafulltypenameanditisnotanalias.Youcanprovidetheconfigurationsectionwiththenamespacesandassembliestolookthroughbyusingthe<namespace>and<assembly>elements,asshowninthefollowingexample.XML

<unityxmlns="http://schemas.microsoft.com/practices/2010/unity">

<namespacename="MyApp.Interfaces"/>

<namespacename="System"/>

<assemblyname="MyApp”/>

<assemblyname="mscorlib,2.0.0.0,Culture=neutral,PublicKeyToken=b77a5c561934e089"/>

...

</unity>

Withtheconfigurationshowninthepreviousexample,whentheconfigurationsystemhitsanameitdoesnotrecognizeasatypenameoralias,itwillthensearchthroughtheassembliesandnamespacesforamatch.So,tofindILogger,itwilltrytomatchthefollowingnamesinorder:

1. MyApp.Interfaces.ILogger,MyApp2. System.ILogger,MyApp3. MyApp.Interfaces.ILogger,mscorlib,2.0.0.0,Culture=neutral,

PublicKeyToken=b77a5c561934e0894. System.ILogger,mscorlib,2.0.0.0,Culture=neutral,

PublicKeyToken=b77a5c561934e089

Thesearchwillstopatthefirstmatchingtype.

Thesystemusessimplestringconcatenationtocreatethetypenameitattemptstoload.However,youcannotspecifyanamespacequalifiednameplusthetype,MyApp.Interfaces.ILogger,MyApp,ifyouhaveanynamespaceelementsinyourconfigurationsection,<namespacename="System"/>.Thenamespacefromtheconfigurationsectionwillbeappendedtothenamespace,resultinginasearchonthewrongname,System.MyApp.Interfaces.ILogger.Youshouldputnamespacesinthe<namespace>elementsinsteadofonthetypenamesintheconfigurationfiletoavoidthispossibility.

Ifyouhavealargenumberofassembliesandnamespaces,thenthesystemtypesearchcouldtakeasignificantamountoftimetocomplete.Normally,containersareonlyconfiguredatapplicationstartup,sothistimehitwillnotbesignificantduringtheoperationofyourapplication.Ifyoufinditbecomesasignificantissue,thenyoushouldconsiderusinganexplicitaliasforthetypesthattakethegreatestsearchtimes,sincealiasesarematchedfirst.

Whenmatchinganamewithatype,theconfigurationsystemperformsthefollowingstepsinorder.Thefirstonetosucceedstopstheprocess:

1. Attempttoloadatypeusingthenamedirectly(treatedasafulltypename)

2. Attempttomatchanametoanalias3. Doautomatictypesearch

DefaultAliasesandAssembliesSometypesandassembliesareusedfrequentlyinUnityconfigurationfiles.TheUnityconfigurationsystemprovidesasetofpredefineddefaultaliasessoyoudonothavetoexplicitlyaddaliasesforthesecommontypes.Anyuser-definedentrieswilloverwritethedefaultones.

Note:Aliasesarecasesensitive.

Inadditiontothedefaultaliases,theUnityconfigurationsystemalsoautomaticallyaddsSystemandmscorlibassembliestothelistofassembliesthataresearchedfortypes.

Thefollowingtablehasthecompletelistofpre-definedtypealiasesprovidedbyUnity:

DefaultAlias Type

sbyte System.SByte

short System.Int16

int System.Int32

integer System.Int32

long System.Int64

byte System.Byte

ushort System.UInt16

uint System.UInt32

ulong System.UInt64

float System.Single

single System.Single

double System.Double

decimal System.Decimal

char System.Char

bool System.Boolean

object System.Object

string System.String

datetime System.DateTime

DateTime System.DateTime

date System.DateTime

singleton Microsoft.Practices.Unity.ContainerControlledLifetimeManager

ContainerControlledLifetimeManager Microsoft.Practices.Unity.ContainerControlledLifetimeManager

transient Microsoft.Practices.Unity.TransientLifetimeManager

TransientLifetimeManager Microsoft.Practices.Unity.TransientLifetimeManager

perthread Microsoft.Practices.Unity.PerThreadLifetimeManager

PerThreadLifetimeManager Microsoft.Practices.Unity.PerThreadLifetimeManager

external Microsoft.Practices.Unity.ExternallyControlledLifetimeManager

ExternallyControlledLifetimeManager Microsoft.Practices.Unity.ExternallyControlledLifetimeManager

hierarchical Microsoft.Practices.Unity.HierarchicalLifetimeManager

HierarchicalLifetimeManager Microsoft.Practices.Unity.HierarchicalLifetimeManager

resolve Microsoft.Practices.Unity.PerResolveLifetimeManager

perresolve Microsoft.Practices.Unity.PerResolveLifetimeManager

PerResolveLifetimeManager Microsoft.Practices.Unity.PerResolveLifetimeManager

CopyCode

GenericTypesTheCLRtypenamesyntaxforgenerictypesisextremelyverbose,anditalsodoesnotallowforthingslikealiases.TheUnityconfigurationsystemallowsforashorthandsyntaxforgenerictypesthatalsoallowsforaliasesandtypesearching.

Tospecifyaclosedgenerictype,youprovidethetypenamefollowedbythetypeparametersinacomma-separatedlistinsquarebrackets.

TheUnityshorthandwouldlooklikethefollowingexample.XML

<container>

<registertype="IDictionary[string,int]"</register>

</container>

Ifyouwishtouseanassemblyname-qualifiedtypeasatypeparameter,ratherthananaliasoranautomaticallyfoundtype,youmustplacethatentirenameinsquarebrackets,asshowninthefollowingexample:XML

<registertype="IDictionary[string,[MyApp.Interfaces.ILogger,MyApp]]"/>

Tospecifyanopengenerictypeyousimplyleaveoutthetypeparameters.Youhavetwooptions:

UsetheCLRnotationof`NwhereNisthenumberofgenericparameters.Usethesquarebrackets,withcommas,toindicatethenumberofgenericparameters.

GenericType ConfigurationfileXMLusingCLRnotation

ConfigurationfileXMLusingcommanotation

IList<T> IList`1 IList[]

IDictionary<K,V> IDictionary`2 IDictionary[,]




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Specifying Types in the Configuration File'%0AEntLib50_e796f090-a8b9-4cd3-b5dd-aead46cc3333%0APlease provide details of the error you have located...%0A


TheUnityConfigurationSchema

Unity2.0usesanewstreamlinedconfigurationschemaforconfiguringUnity.

Thefollowingsectionsdescribetheschemaconfigurationelements,theirchildelements,andtheirattributesinmoredetail:

The<unity>ConfigurationSectionThe<container>ElementThe<register>ElementThe<lifetime>ElementThe<constructor>ElementThe<property>ElementThe<method>ElementThe<param>ElementThe<dependency>ElementThe<value>ElementThe<optional>ElementThe<array>ElementThe<extension>ElementThe<instance>ElementThe<namespace>ElementThe<alias>ElementThe<sectionExtension>Element

The<unity>ConfigurationSection

http://schemas.microsoft.com/practices/2010/unity

The<register>Element

The<lifetime>Element

The<constructor>Element

The<property>Element

The<method>Element

The<param>Element

The<dependency>Element

The<value>Element

The<optional>Element

The<array>Element

The<extension>Element

The<instance>Element

The<namespace>Element

The<assembly>Element

The<alias>Element

The<sectionExtension>ElementToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Unity Configuration Schema'%0AEntLib50_d3f74a92-c473-4a9e-83ca-dfcff759912f%0APlease provide details of the error you have located...%0A


SpecifyingValuesforInjection

ThistopicexplainshowtoconfiguretheinformationrequiredsothatUnitywillautomaticallypopulateconstructorandmethodparametersandpropertyvalueswhenitresolvesinstancesoftypes.The<param>and<property>elementsbothletyouspecifyavaluetobesuppliedfortheparameterorproperty,respectively.Therearemanydifferentkindsofvaluesthatcanbespecified,eachwithaseparateelement.Inaddition,theUnityconfigurationschemasupportsashorthandnotationforthemostcommoncases.

FormoreinformationabouttheformatoftheUnityconfigurationfile,seeUsingDesign-TimeConfiguration.

Thistopiccontainsthefollowingsectionsdescribingvaluesforinjection:

ResolvingValuesfromtheContainer

GivingValuesinConfiguration

ConfiguringArrayValues

ResolvingValuesfromtheContainer

GivingValuesinConfiguration

ConfiguringArrayValuesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Specifying Values for Injection'%0AEntLib50_2995dc15-f75b-43ed-8eb4-79950cfc6d78%0APlease provide details of the error you have located...%0A


ExtendingtheUnityConfigurationSchema

TheUnitycontainerishighlycustomizable.Noonefixedconfigurationformatcancovereverythingthatyoumightwanttodowiththecontainer.Asaresult,theUnityconfigurationsystemitselfisextensible,allowingyoutoaddnewvalidelementstoyourconfigurationfile.The<sectionExtension>elementallowsyoutoloadthecodethataddsthesenewoptionstotheconfigurationfile.ThisletsyouspecifyanimplementationoftheSectionExtensiontype.

Sectionextensionscandothefollowingtotheconfiguration:AddnewpredefinedaliasesAddnewcontainer-levelelementsAddnewregistration-levelelementsAddnewvalue-levelelements

Youcancreateyourowncustomextensions,oruseextensionscreatedbythirdparties,withUnity.Unityalsousesdefaultextensionstoimplementitsownfunctionality.Forinformationaboutusingextensions,seeCreatingandUsingContainerExtensions.

OneexampleofasectionextensionistheInterceptionConfigurationExtensionsectionextension,whichshipswiththeUnitypackage.Thissectionextensionaddsthefollowingelementsandaliasestotheschema:

Aliasesaredefinedforeachofthetypes(likeVirtualMethodInterceptor,TransparentProxyInterceptor,andvariousmatchingrules)thatareusedbytheinterceptionconfiguration.The<interception>elementisaddedasavalidelementchildelementforthe<container>element.The<interceptor>,<interceptionBehavior>,<addInterface>,and<policyInjection>elementsareaddedasvalidchildelementsforthe<register>element.

Thisextensionmechanismallowsforalmostunlimitedextensibilityoftheconfigurationfileonanopt-inbasis.Thoughtheschemaextensionwillmodifytheschemaallowedatruntime,itdoesnotmodifytheXSDfileusedbyVisualStudioIntelliSense.Asaresult,youwillstillgetwarningsintheVisualStudio

XMLeditoreventhoughthefilewillworkfineatruntime.Inordertoresolvethisproblem,thesectionextensionauthormustprovideanupdatedXSDdocumentforusewiththeirextension.Note:

TheInterceptionConfigurationExtensionissupportedbytheschemashippedwithUnity.

The<sectionExtension>elementalsoacceptsauser-providedprefixattribute.Thisisusefulinthecasewheretwosectionextensionsbothprovideextensionelementswiththesamename.Inthecaseofacollision,youcanspecifyaprefixforoneorbothsectionextensions,andthenusethatprefixtodisambiguatethem.

Considertwoschemaextensions,bothofwhichadda<containerCustomization>element.Usingtheprefixattribute,aconfigurationfilethatusesbothwouldlooklikethefollowingexample.XML

<unity>

<sectionExtensionprefix="ext1"type="MyFirstExtension,MyStuff"/>

<sectionExtensionprefix="ext2"type="MySecondExtension,MyOtherStuff"/>

<container>

<ext1.containerCustomization/>

<ext2.containerCustomization/>

</container>

</unity>




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending the Unity Configuration Schema'%0AEntLib50_467eca90-d4fc-4159-8387-a718194ca5dd%0APlease provide details of the error you have located...%0A


ConfigurationFilesforInterception

Unity2.0treatsinterceptionlikeanyextensionyouaddtoUnity.AswithanyextensioninUnity2.0,theUnityinterceptionmechanismcanbeconfiguredthrougheithertheAPIorthroughaUnityconfigurationsection.

Note:Unityprovidespartialbackwardcompatibilityforimplementinginterceptionthroughacontainer.EarlierversionsusedacontainerextensionnamedInterceptionExtension,whichresidesintheassemblynamedMicrosoft.Practices.Unity.Interception.dll.Toconfigureinterception,youspecifythisextensioninthe<extensions>elementofyourapplicationconfiguration,andthendefinethebehaviorofinterceptioninthe<extensionConfig>section.UsingtheextensionandregisterelementsinUnity2.0iscomparabletoInterceptorelementuseintheextensionConfigsectioninearlierversions.Formoreinformationonbackwardcompatibility,seeReusingConfigurationFilesBasedonaPreviousSchema.FormoreinformationaboutUnity1.2interception,seeUsingInterceptionwithUnityonMSDN.

Thistopiccontainsthefollowingsectionstodescribetheinterceptionconfigurationfile:

UsingtheConfigurationFiletoEnableInterceptionStandardInterceptionAliasesEnablingInterceptionofaTypeConfiguringPolicyInjectionPoliciesLegacyInterceptionConfigurationInterceptionConfigurationSchemaElementsRegisteringInterceptionatRunTime


UsingtheConfigurationFiletoEnableInterception





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuration Files for Interception'%0AEntLib50_af2f3726-4a3e-4e31-8f97-ebca0db3d907%0APlease provide details of the error you have located...%0A


InterceptionConfigurationSchemaElements

Whenconfiguringfilesforinterception,thefollowingelementsmayappearaschildrenofa<register>element.FormoreinformationseeTheregisterElement.Theseelementsareusedtodescribethe<interceptors>and<policies>elements,theirchildelements,andtheirattributesinmoredetail:

The<interceptor>ElementThe<interceptionBehavior>ElementThe<addInterface>ElementThe<interception>ElementThe<policy>ElementThe<matchingRule>ElementThe<callHandler>ElementThe<interceptors>ElementTheinterceptors<interceptor>ElementThe<default>ElementThe<key>Element

Formoreinformationaboutinterception,andselectingtheobjectsandtheirmemberstoaddahandlerpipeline,seeUsingInterceptionandPolicyInjection.

The<interceptor>Element

The<interceptionBehavior>Element

The<addInterface>Element

The<interception>Element

The<policy>Element

The<matchingRule>Element

The<callHandler>Element

The<interceptors>Element

Theinterceptors<interceptor>Element

The<default>Element

The<key>ElementToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Interception Configuration Schema Elements'%0AEntLib50_8e2227ed-85a0-47a9-8161-9f363668fb16%0APlease provide details of the error you have located...%0A


Run-TimeConfiguration

ThistopicexploresthetechniquesyoucanusetoconfigureUnitycontainersusingcodethatexecutesatruntimeandcallstheregistrationmethodsoftheUnitycontainer.Itcontainsthefollowingtopics:

UsingRun-TimeConfiguration.ThistopicdescribesthefluentinterfacethatUnityexposes,andotherissuesyoushouldbeawareofwhenconfiguringthecontaineratruntimeusingcode.RegisteringTypesandTypeMappings.Thistopicexplainshowtoregistermappingsinthecontainerbetweentypes.Ingeneral,youwillcreatemappingsbetweenaninterfaceandatypethatimplementstheinterface,orbetweenabaseclassandatypethatinheritsthatbaseclass.CreatingInstanceRegistrations.Thistopicexplainshowtoregisterexistingobjectsinthecontainerthatyoucanresolveinyourapplication.ThistechniqueisusefulifyouwantUnitytomanagethelifetimeoftheobjectsyouregister.RegisteringInjectedParameterandPropertyValues.ThistopicexplainshowtoregistertheinformationrequiredsothatUnitywillautomaticallypopulateconstructorandmethodparametersandpropertyvalueswhenitresolvesinstancesoftypes.RegisteringGenericParametersandTypes.Thistopicexplainshowyoucanregistertheinformationrequiredforinjectionforgenerictypes,includinggenericarrays.RegisteringContainerExtensions.ThistopicexplainshowtoregisterinformationthatinstructsUnitytoloadandusecontainerextensionsthataddadditionalfunctionalitytothecontainer,andhowyoucanregisterconfigurationinformationfortheseextensions.RegisteringInterception.Thistopicexplainshowtoregisterbehaviors,policies,handlers,andmatchingrulesthatUnitywillusewhencreatinginstancesoftypestowhichyouwanttoaddinterceptioncapabilitiestochangethebehaviorofthatobjectortype.

ForinformationabouthowtoconfigureUnityatdesigntime,includingthetechniquesforloadingconfigurationfromafileorothersource,seeDesign-TimeConfiguration.Forinformationaboutresolvingtypesatruntime,see

ResolvingObjects.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Run-Time Configuration'%0AEntLib50_38639e6f-345a-4049-8015-f670458dccad%0APlease provide details of the error you have located...%0A


UsingRunTimeConfiguration

Thistopicdiscussessomeofthefactorsyoushouldkeepinmindwhenusingrun-timeconfiguration,andexplainssomefeaturesoftheUnityrun-timeconfigurationmechanism.Fordetailsonhowtospecifyconfigurationusingaconfigurationfile,seeDesign-TimeConfiguration.

UsingtheUnityContainerFluentInterfaceToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Run Time Configuration'%0AEntLib50_82d55160-31da-43ad-8d60-1445fd1e87cd%0APlease provide details of the error you have located...%0A


RegisteringTypesandTypeMappings

Thistopicexplainshowtoregistertypesinthecontainer.Registeringatypeletsyouconfigurehowthecontainercreatesinstancesofthespecifiedtype.Ingeneral,youwillcreatemappingsbetweenaninterfaceandatypethatimplementstheinterface,orbetweenabaseclassandatypethatinheritsthatbaseclass.However,youcanregistertypesinthecontainerwithoutcreatingamapping.

TheRegisterTypemethodregistersatypewiththecontainer.Attheappropriatetime,thecontainerwillbuildaninstanceofthetypeyouspecify.ThiscouldbeinresponsetodependencyinjectionthroughclassattributesorwhenyoucalltheResolvemethod.Thelifetimeoftheobjectitbuildswillcorrespondtothelifetimeyouspecifyintheparametersofthemethod.Ifyoudonotspecifyavalueforthelifetime,thetypeisregisteredforatransientlifetime,whichmeansthatanewinstancewillbecreatedoneachcalltoResolve.

ThistopiccontainsthefollowingsectionsthatexplainuseoftheRegisterTypemethod:

RegisteringanInterfaceorClassMappingtoaConcreteTypeRegisteringaNamedTypeRegisteringTypeMappingswiththeContainerUsingaLifetimeManagerwiththeRegisterTypeMethodSummaryoftheRegisterTypeMethodOverloadsMoreInformation

RegisteringanInterfaceorClassMappingtoaConcreteType

RegisteringaNamedType

RegisteringTypeMappingswiththeContainer

UsingaLifetimeManagerwiththeRegisterTypeMethod

SummaryoftheRegisterTypeMethodOverloads




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Registering Types and Type Mappings'%0AEntLib50_468496dd-dd87-484c-94d6-bee08bdd1929%0APlease provide details of the error you have located...%0A


CreatingInstanceRegistrations

Thistopicexplainshowtoregisterexistingobjectsinthecontainerthatyoucanresolveinyourapplication.ThistechniqueisusefulifyoualreadyhaveaninstanceofanobjectthatyouhavepreviouslycreatedandwantUnitytomanageitslifetime,orifyouwantUnitytoinjectthatobjectintootherobjectsthatitisresolving.

TheRegisterInstancemethodregistersanexistinginstancewiththecontainer.Youspecifytheinstancetypeandoptionallifetimeintheparameterlist.Thecontainerwillreturnthespecifiedexistinginstanceforthedurationofthespecifiedlifetime.TheRegisterInstancemethodoverloadsareverysimilartotheRegisterTypemethodoverloads,buttheyacceptanadditionalparameter,theobjectinstancetoregister.Theuseoftheregistrationtypeandanoptionalnameareidenticalforthetwomethods.

Whenresolvingtypeswithdependencies,instancesofobjectsaddedtothecontainerwiththeRegisterInstancemethodactjustlikethoseregisteredthroughRegisterType.TheRegisterTypemethodwithaContainerControlledLifetimeManagerautomaticallygeneratesthissingleinstancethefirsttimeyourcodecallsit,whiletheRegisterInstancemethodacceptsanexistinginstanceforwhichitwillreturnreferences.Ifyoudonotspecifyalifetimemanager,thecontainerwilluseaContainerControlledLifetimeManageranditwillreturnareferencetotheoriginalobjectoneachcalltoResolve.

Thistopiccontainsthefollowingsections,whichexplaintheuseoftheRegisterInstancemethod:

RegisteringanExistingObjectInstanceofanInterfaceorTypetoaContainerUsingaLifetimeManagerwiththeRegisterInstanceMethodSummaryoftheRegisterInstancesMethodOverloadsMoreInformationonUsingtheRegisterInstanceMethod

RegisteringanExistingObjectInstanceofanInterfaceorTypetoaContainer

UsingaLifetimeManagerwiththeRegisterInstanceMethod

SummaryoftheRegisterInstanceOverloads




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Instance Registrations'%0AEntLib50_e8b7c7ca-f197-45c2-aeec-33d9953b11e3%0APlease provide details of the error you have located...%0A


RegisteringInjectedParameterandPropertyValues

ThistopicexplainshowtoconfigureacontainertoperformdependencyinjectionatruntimebyusingtheRegisterTypemethodoverloadswiththeInjectionMembersparameterandavoidrelyingonannotatingtheclassestoresolvewithattributes.ThistopicincludesinformationonconfiguringUnitytoautomaticallypopulateconstructorandmethodparametersandpropertyvalueswhenitresolvesinstancesoftypes.

ThistopiccontainsthefollowingsectionstoexplaintheuseoftheInjectionMembersmethods:

RegisteringInjectionforParametersPropertiesandMethodsUsingInjectionMembersInjectingArraysatRunTimeSummaryoftheInjectionMemberMethodsandOverloadsForMoreInformationonInjectionMembers

CopyCode

CopyCode

RegisteringInjectionforParameters,Properties,andMethodsusingInjectionMembersTheRegisterTypeoverloadsallowforconfiguringinjectionbyacceptingInjectionMembers.IncludetheInjectionConstructor,InjectionProperty,andInjectionMethodclassesasaRegisterTypeparametertoprovidedependencyinjectionconfigurationinacontainerforInjectionMemberobjects.

ThefollowingexampleshowsthegeneralsyntaxforusinganInjectionMembersubclass,InjectionConstructor,withtheRegisterTypemethod.Inthisexamplethedefaultconstructoriscalled.C#

IUnityContainercontainer=newUnityContainer()

.RegisterType<AType>(newInjectionConstructor());

ATypeaType=container.Resolve<AType>();

VisualBasic

DimcontainerAsIUnityContainer=NewUnityContainer()_

.RegisterType(OfAType)(NewInjectionConstructor())

DimaTypeAsAType=container.Resolve(OfAType)()

YoucanalsouseattributesappliedtotargetclassmemberstoinstructUnitytoinjectdependentobjects.Formoreinformation,seeUsingInjectionAttributes.

YoucanusetheRegisterTypeoverloadstodothefollowing:RegisterConstructorsandParametersSpecifyaPropertyforInjectionSpecifyaMethodforInjection

RegisterConstructorsandParameters

SpecifyaPropertyforInjection

SpecifyaMethodforInjection

InjectingSpecificArrayInstances

InjectingAllArrayNamedInstances




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Registering Injected Parameter and Property Values'%0AEntLib50_b3a80395-9fff-44ef-8123-666a2ea79131%0APlease provide details of the error you have located...%0A


RegisteringGenericParametersandTypes

Thistopicexplainshowyoucanregistertheinformationrequiredforinjectionforgenerictypes,includinggenericarrays.YoucanspecifyagenerictypewhenyouregisteratypeintheUnitycontainerinalmostexactlythesamewayasyouregisternon-generictypes.Unityprovidestwoclassesspecificallyforregisteringgenerics,GenericParameterforspecifyingthataninstanceofagenerictypeparametershouldberesolved,andGenericResolvedArrayParameterforspecifyingthatanarraycontainingtheregisteredinstancesofagenerictypeparametershouldberesolved.

Seethe"SpecifyingTypesintheConfigurationFile"sectionintheSpecifyingTypesintheConfigurationFiletopicformoredetailsongenerics,includingadiscussionofunbounded,closed,andopengenerictypes.

Thistopiccontainsthefollowingsectionsthatexplainregisteringgenerics:RegisteringGenericInterfacesandClassesRegisteringTypeMappingsForGenericsRegisteringGenericArraysSupportforGenericDecoratorChainsMethodsforRegisteringGenericParametersandTypesMoreInformation

RegisteringGenericInterfacesandClasses

RegisteringTypeMappingsforGenerics

RegisteringGenericArrays

MethodsforRegisteringGenericParametersandTypes




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Registering Generic Parameters and Types'%0AEntLib50_0394f9ca-6683-4020-a13e-a156ff2046d8%0APlease provide details of the error you have located...%0A


RegisteringContainerExtensions

ThistopicexplainshowtoregisterinformationthatinstructsUnitytoloadandusecontainerextensionsthataddadditionalfunctionalitytothecontainer,andhowyoucanregisterconfigurationinformationfortheseextensions.

Thistopiccontainsthefollowingsectionsthatexplaincontainerextensions:AddingandRemovingExtensionsAccessingConfigurationInformationforExtensionsMethodsforRegisteringandConfiguringContainerExtensionsMoreInformation

AddingandRemovingExtensions

AccessingConfigurationInformationforExtensions

MethodsforRegisteringandConfiguringContainerExtensions




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Registering Container Extensions'%0AEntLib50_9bf7c7a4-74ad-47a5-92ac-c7e497663b2a%0APlease provide details of the error you have located...%0A


RegisteringInterception

Thistopicexplainsrun-timeregistrationofthevariousinterceptionelements,includinginterceptors,behaviors,policies,handlers,andmatchingrulesthatUnityusestoconfigureacontainerforinterception.Theconfigurationinformationisusedwhencreatinginstancesoftypesforwhichyouwanttoaddinterceptioncapabilitiestochangethebehaviorofthatobjectortype.Inordertoprovidebackwardcompatibility,Unity2.0supportscallingtheolderAPISetInterceptorForandSetDefaultInterceptorFormethodsontheInterceptioncontainerextensioninadditiontosupportingtheUnity2.0approachusingtheRegisterTypeAPItoexplicitlyconfigureinterceptors,behaviors,andadditionalinterfaces.

RegisteringInterceptorsandInterceptorBehaviorsExplicitlyUsingRegisterTypeDefaultInterceptorforaTypeRegisteringAdditionalInterfaceRegisteringPolicyInjectionComponents

Forinformationonusingaconfigurationfiletoconfigureacontainerforinterception,seeConfigurationFilesforInterception.

ForinformationonthedesignofUnityinterceptionseeInterceptionwithUnity.

Forinformationonusinginterceptionwithoutadependencyinjection(DI)container,seethe"StandAloneUnityInterception"sectioninUsingInterceptioninApplications.

CopyCode

CopyCode

RegisteringInterceptorsandInterceptorBehaviorsExplicitlyUsingRegisterTypeUnity2.0enablesinterceptionlikeanyothercontainerextensionbyusingcontainer.AddNewExtension.Thenyoucanconfigureatypeforinterceptionusinganinterceptorofyourchoosing,withbehaviorsofyourchoosing.InUnity2.0youexplicitlyconfigurewhichobjectistobeinterceptedbywhichinterceptionmechanismandspecifythebehaviorbyusingInterceptionBehavior;Unity1.2implicitlysetuppolicyinjectionwhenyouconfiguredaninterceptor.Thefollowingexampleshowshowtoconfigureinterceptionforatypeandturnonacustombehavior.ThisexamplefirstaddstheInterceptionextensionbycallingAddNewExtension,andthenusesRegisterTypetoregisteraVirtualMethodInterceptorandaninterceptionbehavior.Thebehaviormustbedefinedelsewhere.C#

IUnityContainercontainer=newUnityContainer();

container.AddNewExtension<Interception>();

container.RegisterType<TypeToIntercept>(

newInterceptor<VirtualMethodInterceptor>(),

newInterceptionBehavior<CustomBehavior>());

VisualBasic

DimcontainerAsIUnityContainer=NewUnityContainer()

container.AddNewExtension(OfInterception)()

container.RegisterType(OfTypeToIntercept)(_

NewInterceptor(OfVirtualMethodInterceptor)(),_

NewInterceptionBehavior(OfCustomBehavior)())

UsingthisoverloadoftheInterceptorconstructoractuallytellsthecontainertoresolvetheinterceptorthroughthecontainer.Youcanpassanoptionalstring,whichbecomesthenametoresolvewith.Inmostapplicationsyouwouldsimplyleavethisblank,butifyouhaveimplementedcustominterceptors,youmightwanttoprovideadditionalconfiguration.ThereisanotheroverloadoftheInterceptorconstructoryoucanusetospecifytheinterceptorsandbehaviors

CopyCode

CopyCode

bycreatinginstancesandpassingtheactualinstancesintothecontainer,asdoneinthefollowingexample:C#

//Addtheinterceptionextensiontothecontainer

IUnityContainercontainer=newUnityContainer();

container.AddNewExtension<Interception>();

//Configureinterception

container.RegisterType<IInterface,BaseClass>(

"myInterceptor",

newInterceptor(newInterfaceInterceptor()),

newInterceptionBehavior(newCustomBehavior()),

newInterceptionBehavior(newSomeOtherBehavior()));

VisualBasic

'Addtheinterceptionextensiontothecontainer

DimcontainerAsIUnityContainer=NewUnityContainer()

container.AddNewExtension(OfInterception)()

'Configureinterception

container.RegisterType(OfIInterface,BaseClass)_

("myInterceptor",_

NewInterceptor(NewInterfaceInterceptor()),_

NewInterceptionBehavior(NewCustomBehavior()),_

NewInterceptionBehavior(NewSomeOtherBehavior()))

DefaultInterceptorforaType





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Registering Interception'%0AEntLib50_53570dcb-4520-4e42-b64d-84c9222841c0%0APlease provide details of the error you have located...%0A


RegisteringPolicyInjectionComponents

Thistopicexplainshowtoregisterthevariouselements,includinginterceptors,behaviors,policies,callhandlers,andmatchingrulesthatUnityusestoconfigureacontainerforinterceptionandforapolicyinjectionbehavior.

Whenyouconfigurepolicyinjectionyoumustspecifywhichobjectswillbeinterceptedwiththepolicyinjectionbehaviorandwhichpoliciesinthecontaineraretobeused.Thenwhenbuildingtheobject,thepolicyinjectionbehaviorissetupusingthepoliciesalreadydefinedinthecontainer.

Thistopiccontainsthefollowingsections:PolicyInjectionRun-TimeConfigurationDefiningPoliciesbyUsingtheAPI

PolicyInjectionRun-TimeConfigurationTherearetwostepstoconfiguringatypeforpolicyinjection.First,youmustregisterthetypeinthecontainer.Inthatregistration,youmustconfigureaninterceptorandenablethePolicyInjectionBehavior.Second,youmustconfigurethepolicyinjectionpoliciesthatdeterminewhichcallhandlersexecuteonwhichmethods.C#

intintercepted=0;

varcontainer=newUnityContainer();

container

.AddNewExtension<Interception>()

.RegisterType<ActionCallHandler>()

//Registerthetypetobeintercepted

.RegisterType<InterceptedType>(

newInterceptor<TransparentProxyInterceptor>(),

newInterceptionBehavior<PolicyInjectionBehavior>())

//Configurepolicies

.Configure<Interception>()

.AddPolicy("policy")

.AddCallHandler(newActionCallHandler(()=>intercepted++))

.AddMatchingRule(newMemberNameMatchingRule("MethodX"));

VisualBasic

DiminterceptedAsInteger=0

Dimcontainer=NewUnityContainer()

container_

.AddNewExtension(OfInterception)()_

.RegisterType(OfActionCallHandler)()_

'Registerthetypetobeintercepted

.RegisterType(OfInterceptedType)(_

NewInterceptor(OfTransparentProxyInterceptor)(),_

NewInterceptionBehavior(OfPolicyInjectionBehavior)())_

'Configurepolicies

.Configure(OfInterception)()_

.AddPolicy("policy")_

.AddCallHandler(NewActionCallHandler(Function()_

System.Math.Max(System.Threading.Interlocked.Increment_

(intercepted),intercepted-1)))

DefiningPoliciesbyUsingtheAPIToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Registering Policy Injection Components'%0AEntLib50_2090aa6d-38c7-4527-a211-aa4fa966e855%0APlease provide details of the error you have located...%0A


UsingUnityinApplications

ThistopicdescribeshowtodevelopapplicationsusingUnity,andhowtocreateandbuildinstancesofobjects.ItassumesthatyouunderstandhowtoconfiguretheUnitycontainer.Thissectionincludesthefollowingtopics:

ApplicationDesignConceptswithUnity.ThistopicexplainshowUnitycanhelpyoutoimplementcommondesignpatternsandachievedecouplingandcoherenceinyourdesigns.AddingUnitytoYourApplication.ThistopicdescribeshowtoaddUnitytoyourproject,andhowtoreferencetheappropriateassembliesinyourcode.ResolvingObjects.ThistopiccontainsaseriesofsectionsthatdescribehowyoucanresolveobjectsthroughtheUnitycontainersothatitcreatestheappropriatetypeandoptionallypopulatesanydependenciesspecifiedforthesetypes.UnderstandingLifetimeManagers.ThistopicdescribesthewaythatUnitymanagesthelifetimeofobjectsitcreates,andhowyoucanusethelifetimemanagersincludedwithUnity.UsingContainerHierarchies.ThistopicexplainshowyoucanuseahierarchyofnestedUnitycontainerstoachievefinelygrainedcontrolovertheconfigurationofUnityandmanagethisconfigurationatruntime.

ForinformationonhowtoconfigureUnity,seeConfiguringUnity.

Unityshipsasbothsourcecodeandsignedbinaryassemblies.Youcanusethesignedassembliesdirectly.Ifyouintendtocompilethesourcecode,seeTargetAudienceandSystemRequirements.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Unity in Applications'%0AEntLib50_5b85cb17-d9cc-4eea-b07b-030c2b740ef6%0APlease provide details of the error you have located...%0A


ApplicationDesignConceptswithUnity

Featuressuchasinversionofcontrol,dependencyinjection,interception,factory,andlifetime(someofwhicharedescribedinthe"ScenariosforUnity"sectionofthetopicWhenShouldIUseUnity?)provideseveralmajoradvantageswhenbuildingapplicationsthatconsistofmanyindividualclassesandcomponents.Designingapplicationsthatconformtothesepatternscanprovidethefollowing:

Thecapabilitytosubstituteonecomponentforanotherusingapluggablearchitecture.Thecapabilitytocentralizeandabstractcommonfeaturesandtomanagecrosscuttingconcernssuchaslogging,authentication,caching,andvalidation.Increasedconfigurationflexibility.Thecapabilitytolocateandinstantiateservicesandcomponents,includingsingletoninstancesoftheseservicesandcomponents.Simplifiedtestabilityforindividualcomponentsandsectionsoftheapplication.Simplifiedoveralldesign,withfasterandlesserror-pronedevelopment.Easeofreuseforcommoncomponentswithinotherapplications.

Ofcourse,implementingthesepatternscaninitiallymakethedesignanddevelopmentprocessmorecomplex,buttheadvantageseasilyjustifythisextracomplexity.Inaddition,theuseofacomprehensivedependencyinjectionmechanismcanactuallymakethetaskofdesigninganddevelopingapplicationsmucheasier.

Fundamentally,therearetwoapproachestousingadependencyinjectionmechanism:

Youcanarrangetohavedependentobjectsautomaticallyinjected,usingtechniquessuchasconstructorinjection,property(setter)injection,andmethodcallinjectionthatinjectdependentobjectsimmediatelywhenyouinstantiatetheparentobject.Thisapproachisgenerallymostappropriateforapplicationsthatrequireapluggablearchitectureorwhereyouwanttomanagecrosscuttingconcerns.Youcanhaveobjectsinjectedonlyondemand,bycallingtheResolve

methodofthecontaineronlywhenyouneedtoretrieveareferencetoaspecificobject.Thisapproachisknownasservicelocator.Itismoreintrusiveintoyourapplication,butcanbesimplerifyourarchitecturedoesnotlenditselftohavingacentralcontainer.

Inadditiontodependencyinjection,developersmaywishtoimplementpatternssuchasInterception,Decorator,ChainOfResponsibility,andInterceptingFilter,whereacallfromaclientorprocesspassesthroughagraphofobjects,witheachoneabletoaccessandactupondetailsofthecall,suchasthemethodorpropertyname,theparametertypesandvalues,thereturnedtypeandvalue,andotherinformation.Unityachievesthisthroughinterceptionofmethodcalls,providingopportunitiestoapplypoliciestoobjectsusingatechniqueoftenreferredtoaspolicyinjection.

Unityprovidesacomprehensivedependencyinjectionandinterceptionmechanism,andiseasytoincorporateintoyourapplications.However,itdoeschangethewaythatyoudesigntheseapplications.Thefollowingsectionsofthistopicdescribeareaswheredependencyinjectionisuseful:

PluggableArchitecturesManagingCrosscuttingConcernsServiceandComponentLocationPolicyInjectionthroughInterception

PluggableArchitectures

ManagingCrosscuttingConcerns

ServiceandComponentLocation

PolicyInjectionthroughInterceptionToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Application Design Concepts with Unity'%0AEntLib50_c7f3bc41-de51-44aa-a88f-9fe411ca0bed%0APlease provide details of the error you have located...%0A


AddingUnitytoYourApplication

Unityisdesignedtosupportarangeofcommonscenariosforresolvinginstancesofobjectsthat,themselves,dependonotherobjectsorservices.However,youmustfirstprepareyourapplicationtouseUnity.Thefollowingproceduredescribeshowtoincludethenecessaryassembliesandelementsinyourcode.

Toprepareyourapplication1. AddareferencetotheUnityassembly.InVisualStudio,right-click

yourprojectnodeinSolutionExplorer,andthenclickAddReference.ClicktheBrowsetabandfindthelocationoftheMicrosoft.Practices.Unity.dllassembly.Selecttheassembly,andthenclickOKtoaddthereference.

2. (Optional)IfyouintendtousetheconfigurationtypeswhenyoucreateextensionsforUnity,usethesameproceduretosetareferencetotheUnityconfigurationassembly,namedMicrosoft.Practices.Unity.Configuration.dll.

3. (Optional)IfyouintendtousetheinterceptionandpolicyinjectionfeaturesofUnity,usethesameproceduretosetareferencetotheUnityinterceptionassembly,namedMicrosoft.Practices.Unity.Interception.dll.

4. (Optional)IfyouintendtousetheconfigurationtypesfortheinterceptionandpolicyinjectionfeaturesofUnity,usethesameproceduretosetareferencetotheUnityinterceptionconfigurationassembly,namedMicrosoft.Practices.Unity.Interception.Configuration.dll.

5. (Optional)TouseelementsfromUnitywithoutfullyqualifyingtheelementreference,addthefollowingusingstatements(C#)orImportsstatements(VisualBasic)tothetopofyoursourcecodefileasrequired.C#


usingMicrosoft.Practices.Unity.Configuration;

usingMicrosoft.Practices.Unity.InterceptionExtension;

VisualBasic


ImportsMicrosoft.Practices.Unity.Configuration

ImportsMicrosoft.Practices.Unity.InterceptionExtension

6. (Optional)IfyouareusingtheIServiceLocatorinterface,addareferencetotheservicelocationbinaryMicrosoft.Practices.ServiceLocation.dll.VisualStudiomayautomaticallycopythisfiletoyourbindirectorywhenitcompiles,butyoudonotneedtoincludeitunlessyouareexplicitlyusingtheUnityServiceLocatorAdapterclass.

7. Addyourapplicationcode.FormoreinformationabouthowyoucanuseUnityinyourownapplications,seeWhatDoesUnityDo?

ForVisualBasicprojects,youcanalsousetheReferencespageoftheProjectDesignertomanagereferencesandimportednamespaces.ToaccesstheReferencespage,selectaprojectnodeinSolutionExplorer,andthenclickPropertiesontheProjectmenu.WhentheProjectDesignerappears,clicktheReferencestab.

Note:TherearelimitationswhenusingUnityinapartialtrustenvironment.Formoreinformation,seeUsingUnityinPartialTrustEnvironments.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Adding Unity to Your Application'%0AEntLib50_b9fbb764-15cf-4214-aa87-cfa773a1279e%0APlease provide details of the error you have located...%0A


ResolvingObjects

YoucanusetheUnitycontainertogenerateinstancesofanyobjectthathasapublicconstructor(inotherwords,objectsthatyoucancreateusingthenewoperator),withoutregisteringamappingforthattypewiththecontainer.WhenyoucalltheResolvemethodandspecifythedefaultinstanceofatypethatisnotregistered,thecontainersimplygeneratesandreturnsaninstanceofthattype.However,theonlytimethatthisisrealisticallypracticaliswhentheobjectyouaregeneratingcontainsdependencyattributesthatthecontainerwillusetoinjectdependentobjectsintotherequestedobject.

TheUnitycontaineridentifiestyperegistrationsandtypemappingsinthecontainerusingatypeand,optionally,aname.Thetypeisaninterfaceoraclass(usuallyaninterfaceorbaseclass)thatthedesiredconcreteobjecttypeimplementsorinherits.ThisidentifiesthemappingsothatthecontainercanretrievethecorrectobjecttypeinresponsetoacalltotheResolveorResolveAllmethod.Wherethereismorethanonemappingforthesametype,theoptionalnamedifferentiatesthesemappingsandallowscodetospecifywhichofthemappingsforthattypetouse.

Theprovisionofbothgenericandnon-genericoverloadsofmanyoftheUnitycontainermethodsensuresthatUnitycanbeusedinlanguagesthatdonotsupportgenerics.Youcanuseeitherapproach(thegenericorthenon-genericoverloads)inyourcodeandmixthemasrequired.Forexample,youcanregistermappingsusingthegenericoverloadsandthenretrieveobjectinstancesusingthenon-genericoverloads,andviceversa.

Note:Whenyouattempttoresolveanabstractbaseclassorinterfacewherethereisnomatchingtypemappinginthecontainer,Unitywillattempttocreateanewinstanceoftheclassyouspecified.Asitcannotconstructandpopulateaninstanceofanabstractclassoraninterface,Unitywillraiseanexception.

Whenyouattempttoresolveanon-mappedconcreteclassthatdoesnothaveamatchingregistrationinthecontainer,Unitywillcreateaninstanceofthatclassandpopulateanydependencies.

ThefollowingtopicsdescribehowyoucanresolveobjectsusingtheResolveorResolveAllmethods:

ResolvinganObjectbyType.ResolvinganObjectbyTypeandRegistrationName.ResolvingAllObjectsofaParticularType.ResolvingObjectsbyUsingOverridesRetrievingContainerRegistrationInformation

FormoreinformationabouthowyoucanconfigureUnitywithtyperegistrationsandmappings,seeConfiguringUnity.

Formoreinformationabouthowyoucanperformdependencyinjectiononexistingobjectinstances,seeUsingBuildUptoWireUpObjectsNotCreatedbytheContainer.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Resolving Objects'%0AEntLib50_d6f7381e-3f53-4f83-8e59-7094c4eb20d1%0APlease provide details of the error you have located...%0A


ResolvinganObjectbyType

UnityprovidesamethodnamedResolvethatyoucanusetoresolveanobjectbytype,andoptionallybyprovidingaregistrationname.Registrationsthatdonotspecifyanamearereferredtoasdefaultregistrations.ThistopicdescribeshowtousetheResolvemethodtoresolvetypesandmappingsregisteredasdefaultregistrations.Forinformationaboutresolvingnamedregistrations,seeResolvinganObjectbyTypeandRegistrationName.

TheResolveMethodOverloadsforDefaultRegistrations

UsingtheResolveMethodwithDefaultRegistrations




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Resolving an Object by Type'%0AEntLib50_ba44ce62-c3fc-4d90-b5b6-5fbc4606123d%0APlease provide details of the error you have located...%0A


ResolvinganObjectbyTypeandRegistrationName

UnityprovidesamethodnamedResolvethatyoucanusetoresolveanobjectbytype,andoptionallybyprovidingaregistrationname.Registrationsthatspecifyanamearereferredtoasnamedregistrations.ThistopicdescribeshowtousetheResolvemethodtoresolvetypesandmappingsregisteredasnamedregistrations.Forinformationaboutresolvingdefaultregistrations,seeResolvinganObjectbyType.

TheResolveMethodOverloadsforNamedRegistrations

UsingtheResolveMethodwithNamedRegistrations

ResolvingGenericTypesbyName

MoreInformation

ResolvingGenericTypes




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Resolving an Object by Type and Registration Name'%0AEntLib50_3f2abbd5-5f86-4bbd-89df-b0edb33dc88c%0APlease provide details of the error you have located...%0A


ResolvingAllObjectsofaParticularType

Whenyouwanttoobtainalistofalltheregisteredobjectsofaspecifictype,youcanusetheResolveAllmethod.Thetwooverloadsofthismethodaccepteitheraninterfaceoratypename,andtheyreturnaninstanceofIEnumerablethatcontainsreferencestoallregisteredobjectsofthattypethatarenotdefaultmappings.ThelistreturnedbytheResolveAllmethodcontainsonlynamedinstanceregistrations.TheResolveAllmethodisusefulifyouhaveregisteredmultipleobjectorinterfacetypesusingthesametypebutdifferentnames.YoucanalsousetheparamstoprovideconstructoroverridesfortheResolveAllcalls.

TheResolveAllMethodOverloads

UsingtheResolveAllMethod

ResolvingAllGenericTypesbyNameToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Resolving All Objects of a Particular Type'%0AEntLib50_fee9ada9-400c-4e64-894a-f075e7dfe0c2%0APlease provide details of the error you have located...%0A


ResolvingObjectsbyUsingOverrides

Theparameteranddependencyoverrides,ParameterOverrideandDependencyOverride,areResolverOverrideimplementationsthatprovidesupportforoverridingtheregistrationinformationforresolvinginstancesoftypes.WhenyoucalltheResolvemethod,theseclassesenableyoutooverridevaluesspecifiedwhenthetypewasregistered,suchasbyaRegisterTypeorRegisterInstancestatement.Ineffect,RegisterTypesuppliedvaluesareoverriddenbyResolvesuppliedvalues.

UseParameterOverridetooverridethespecifiedconstructorparameterorparameters.TheoverrideapplieseverywheretheparameterappearsunlessyouuseOnTypetoconstraintheoverridetoaspecifiedtype.Sincethepurposeofoverridesistoaffecttheresolutionofdependenciesforallrelevantcreatedobjects,notjusttheobjectrequestedinthecalltoResolve,unconstrainedoverridescanproduceerrorsifthereareunconstrainedParameterOverrideparametersthatmatchparameterswiththesamenamebutdifferenttypesontheselectedconstructorsforobjectscreatedinagivenresolveoperation.

UsePropertyOverridetooverridethevalueofthespecifiedpropertyorproperties.TheoverrideapplieseverywherethepropertyappearsunlessyouuseOnTypetoconstraintheoverridetoaspecifiedtype.

UseDependencyOverridetooverridethevalueinjectedwheneverthereisadependencyofthegiventype.DependencyOverrideoverridesallinstanceswherethetypematches.Bothparameteroverridesanddependencyoverridessupportgenerictypesandmultipleoverrides.

Note:IftheoverriddenobjectwaspreviouslycreatedandisaSingleton,theoverrideisignored.ThelifetimemanagertakesprecedenceandSingletonsalwaysreturnthesameinstance.Thecontainerdoesnotstoreareferencefortheoverriddenobject.

Overridesworkwiththeconstructorthatisselectedforthetype,byattributeorconfiguration.Iftheconstructortobeusedisnotidentifiedwithanattributeor

explicitcontainerconfiguration,thenthedefaultbehavioristhattheconstructorwiththemostparameterswillbeused.

Aparameterandpropertyoverrideneveraffectswhatelementgetsselected.Theyonlycontrolthevalueofthespecifiedparameterorproperty.Youdonotchangewhichconstructoriscalledwithanoverride,andyoudonotchangewhichpropertiesgetsetwithanoverride.

Note:Ifthepropertyisnotsetasadependencythroughattribute,containerAPI,orconfigurationfile,thentheoverridedoesnothing.

Thistopiccontainsthefollowingsectionstoexplainoverridesinmoredetail:UsingParameterOverridesUsingPropertyOverridesUsingDependencyOverridesMoreInformation

UsingParameterOverrides

UsingPropertyOverrides

UsingDependencyOverrides

MoreinformationToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Resolving Objects by Using Overrides'%0AEntLib50_bd0c4006-a871-4c62-b154-0a7e4de6775f%0APlease provide details of the error you have located...%0A


DeferringtheResolutionofObjects

Unityprovidesatechniquetofacilitateholdingareferencetoanobjectyouneed,butdonotwanttoconstructrightaway.Youwishtodeferresolutionoftheobject.Insteadofcreatingafactoryforthetypeandinjectingthefactoryintoyourclass,thenusingittocreatethetypeyouwantyoucanusethe.NETstandardtypeFunc<T>(C#)orFunc(OfT)(VisualBasic)withtheResolvemethod.Thisreturnsadelegatethat,wheninvoked,callsintothecontainerandreturnsaninstanceofthespecifiedtype(inthiscase,T).

Youcanevencreateadelegateinthiswaywithoutcreatingaregistrationormappingforthespecifiedtypeinthecontainerifyouwish.Becausetheresolveactiononlytakesplacewhenyouinvokethedelegate,subsequentregistrationsaddedtothecontainerareavailablewhenthetargetobjectisresolved.Thismeansthatyoucanmanipulatetheregistrationsandmappingsinthecontaineratanypointbeforeyouresolvethetargetobject(althoughyoucanobviouslyregisterthetypebeforeyoucreatethedelegateifyouprefer).

Forexample,youcancreateadelegateforacomponentnamedMyClass,andthenregisteramappingforitandperformdeferredresolutionwhenrequiredusingthefollowingcode.C#

//CreateaUnitycontainer

IUnityContainermyContainer=newUnityContainer();

//CreateadelegatefortheIMyClassinterfacetype

varresolver=myContainer.Resolve<Func<IMyClass>>();

//...othercodehere...

//RegisteramappingfortheIMyClassinterfacetotheMyClasstype

myContainer.RegisterType<IMyClass,MyClass>();

//Resolvethemappedtargetobject

IMyClassmyClassInstance=resolver();

VisualBasic

'CreateaUnitycontainer

DimmyContainerAsIUnityContainer=NewUnityContainer()

'CreateadelegatefortheIMyClassinterfacetype

Dimresolver=myContainer.Resolve(OfFunc(OfIMyClass))()

'...othercodehere...

'RegisteramappingfortheIMyClassinterfacetotheMyClasstype

myContainer.RegisterType(OfIMyClass,MyClass)()

'Resolvethemappedtargetobject

DimmyClassInstanceAsIMyClass=resolver()

YoucanusethisapproachwhenyouresolvethetypeusingtheResolvemethod,oryoucanspecifythedelegatewhenyouconfigureconstructor,propertysetter,ormethodcallinjection.Youcanalsousenamed(non-default)registrationsbyincludingtheregistrationnameinthecalltotheResolvemethodandtheRegisterTypemethod,justasyouwouldwhenusingthesemethodsfornon-deferredresolution.

Inaddition,youcanusethisfeaturetoperformdeferredresolutionofmultiplenamedregistrations,asanalternativetousingtheResolveAllmethod.Forexample,ifyouhavemultiplenamedregistrationsfortheIMyClassinterfacetosuitableconcretetypes,youcanobtainacollectionoftheresolvedtypes.Thefollowingcodeillustratesthis.C#



//CreateanIEnumerableresolverfortheIMyClassinterfacetype

varresolver=myContainer.Resolve<Func<IEnumerable<IMyClass>>>();


//RegistermappingsfortheIMyClassinterfacetoappropriateconcretetypes

myContainer.RegisterType<IMyClass,FirstClass>("First");

myContainer.RegisterType<IMyClass,SecondClass>("Second");

myContainer.RegisterType<IMyClass,ThidClass>("Third");

//Resolveacollectionofthemappedtargetobjects

IEnumerable<IMyClass>myClassInstances=resolver();

VisualBasic



'CreateanIEnumerableresolverfortheIMyClassinterfacetype

Dimresolver=myContainer.Resolve(OfFunc(OfIEnumerable(OfIMyClass)))()


'RegistermappingsfortheIMyClassinterfacetoappropriateconcretetypes

myContainer.RegisterType(OfIMyClass,FirstClass)("First")

myContainer.RegisterType(OfIMyClass,SecondClass)("Second")

myContainer.RegisterType(OfIMyClass,ThidClass)("Third")

'Resolveacollectionofthemappedtargetobjects

DimmyClassInstancesAsIEnumerable(OfIMyClass)=resolver()

Youcanalsousethedeferredresolvertoresolveinstanceregistrations.Forexample,thefollowingcodeshowshowyoucanresolveanIEnumerablecollectionofstringvalues.C#



//CreateanIEnumerableresolverforstringinstanceregistrations

varresolver=myContainer.Resolve<Func<IEnumerable<string>>>();


//RegistermappingsfortheIMyClassinterfacetoappropriateconcretetypes

myContainer.RegisterInstance("one","FirstString");

myContainer.RegisterInstance("two","SecondString");

myContainer.RegisterInstance("three","ThirdString");

//Resolveacollectionofthestrings

IEnumerable<string>myStringInstances=resolver();

VisualBasic



'CreateanIEnumerableresolverforstringinstanceregistrations

Dimresolver=myContainer.Resolve(OfFunc(OfIEnumerable(OfString)))()


'RegistermappingsfortheIMyClassinterfacetoappropriateconcretetypes

myContainer.RegisterInstance("one","FirstString")

myContainer.RegisterInstance("two","SecondString")

myContainer.RegisterInstance("three","ThirdString")

'Resolveacollectionofthestrings

DimmyStringInstancesAsIEnumerable(OfString)=resolver()




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deferring the Resolution of Objects'%0AEntLib50_6e58e973-df39-4653-9735-2b61221fb1ae%0APlease provide details of the error you have located...%0A


RetrievingContainerRegistrationInformation

Youcanretrievealistofregistrationsfromacontainer,andcheckifaspecificregistrationisinthecontainer.

Thistopiccontainsthefollowingsections:ViewingtheContainerRegistrationsandMappingsCheckingfortheExistenceofaSpecificRegistration

ViewingtheContainerRegistrationsandMappings

CheckingfortheExistenceofaSpecificRegistrationToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Retrieving Container Registration Information'%0AEntLib50_509da7f8-bc1b-459b-ab80-9d537631f2f0%0APlease provide details of the error you have located...%0A


UsingContainerHierarchies

Unitysupportsnestedcontainers,allowingyoutobuildcontainerhierarchies.Nestingcontainersenablesyoutocontrolthescopeandlifetimeofsingletonobjects,andregisterdifferentmappingsforspecifictypes.Thistopiccontainsthefollowingsectionsthatdescribehowyoucancreatecontainerhierarchiesandusetheminyourapplications:

ConstructingandDisposingUnityContainersControllingObjectScopeandLifetimeRegisteringDifferentMappingsforSpecificTypes

ConstructingandDisposingUnityContainers

ControllingObjectScopeandLifetime

RegisteringDifferentMappingsforSpecificTypesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Container Hierarchies'%0AEntLib50_73172960-d09d-4617-838d-f075cf358c0f%0APlease provide details of the error you have located...%0A


UnderstandingLifetimeManagers

TheUnitycontainermanagesthecreationandresolutionofobjectsbasedonalifetimeyouspecifywhenyouregisterthetypeofanexistingobject,andusesthedefaultlifetimeifyoudonotspecifyalifetimemanagerforyourtyperegistration.

Whenyouregisteratypeinconfiguration,orbyusingtheRegisterTypemethod,thedefaultbehaviorisforthecontainertouseatransientlifetimemanager.Itcreatesanewinstanceoftheregistered,mapped,orrequestedtypeeachtimeyoucalltheResolveorResolveAllmethodorwhenthedependencymechanisminjectsinstancesintootherclasses.Thecontainerdoesnotstoreareferencetotheobject.However,whenyouwantnontransientbehavior(suchasasingleton)forobjectsUnitycreates,thecontainermuststoreareferencetotheseobjects.Itmustalsotakeovermanagementofthelifetimeoftheseobjects.

UnityusesspecifictypesthatinheritfromtheLifetimeManagerbaseclass(collectivelyreferredtoaslifetimemanagers)tocontrolhowitstoresreferencestoobjectinstancesandhowthecontainerdisposesoftheseinstances.

WhenyouregisteranexistingobjectusingtheRegisterInstancemethod,thedefaultbehaviorisforthecontainertotakeovermanagementofthelifetimeoftheobjectyoupasstothismethodusingtheContainerControlledLifetimeManager.Thismeansthatattheendofthecontainerlifetime,theexistingobjectisdisposed.Youcanalsousethislifetimemanagerwhendefiningregistrationsinconfiguration,orwhenusingtheRegisterTypemethod,tospecifythatUnityshouldmanagetheobjectasasingletoninstance.

Usinganon-defaultlifetimemanagerwithRegisterInstancewillresultindifferentbehaviors,dependingonthecontextoftherequests.

ResolverequestsinthesamecontextwheretheRegisterInstancecallwasmade,suchasthesamethreadifusingaper-threadmanager,orthesameparentcontainerwhenusingthehierarchicalone,willreturntheregisteredinstances.Resolverequestsinothercontexts,suchasadifferentthreadifusingaper-threadmanager,orachildcontainerwhenusingthehierarchical

lifetimemanager,willresultinanewinstancebeingcreatedbythecontaineranditwillbemadethesingletonforthatcontext.Thecreationofaninstanceunderthesecircumstancescouldfailifthecontainercannotresolvetheinstance,forexampleifyouregisteredaninstanceforaninterfacewithnomappingstoamatchingclass.

ForinformationaboutusinglifetimemanagerswiththeRegisterTypeandRegisterInstancemethods,seeRegisteringTypesandTypeMappingsandCreatingInstanceRegistrationsintheRun-TimeConfigurationsectionofthisdocumentation.Forinformationaboutspecifyingthelifetimeofobjectsatdesigntime,seeSpecifyingTypesintheConfigurationFile,andThe<instance>ElementintheDesign-TimeConfigurationsectionofthisdocumentation.

UnityBuilt-InLifetimeManagers




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Understanding Lifetime Managers'%0AEntLib50_45c2dde9-86e0-48dd-af0f-26a7fa3a9cb9%0APlease provide details of the error you have located...%0A


DependencyInjectionwithUnity

Ifyouareusingdependencyinjection(DI)throughaDIcontainerapproachtoyourapplicationdevelopment,youcanuseanyavailableDIcontainerincludingthecontainerprovidedbyUnity.UsingtheUnitydependencyinjectioncontainerprovidesopportunitiesforyoutomoreeasilydecouplecomponents,businessobjects,andservicesyouuseinapplications,andcansimplifyhowyouorganizeandarchitecttheseapplications.

YoucancreateinstancesofobjectsusingtheDIcontainerprovidedbyUnity.Unityisavailableasastand-alonedependencyinjectionmechanism.

Thefollowingsectionsofthistopicwillhelpyoutounderstandtheoverallprocess,anduseUnitydependencyinjectioninyourapplications:

UsingBuildUptoWireUpObjectsNotCreatedbytheContainer.ThistopicexplainshowtouseBuildUptopassexistingobjectinstancesthroughthecontainerinordertoapplydependencyinjectiontothatobject.ThisisanalternativetoresolvingtheobjectusinganyoftheothertechniquesavailablewithUnity.UsingInjectionAttributes.ThistopiccontainsaseriesofsectionsthatdescribehowyoucanuseattributesappliedtomembersoftargetclassestoinstructUnitytoinjectdependentobjectsforconstructorandmethodparameters,andasthevaluesofproperties.CircularReferenceswithDependencyInjection.Thistopicdescribeshowyoushouldbeawareofthepossibilityofcircularreferencesarisingwhenusingdependencyinjectiontechniques.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Dependency Injection with Unity'%0AEntLib50_2e466f36-5b63-4a02-9922-ab4c1c98c36d%0APlease provide details of the error you have located...%0A


UsingBuildUptoWireUpObjectsNotCreatedbytheContainer

UnityexposesamethodnamedBuildUpthatyoucanusetopassexistingobjectinstancesthroughthecontainerinordertoapplydependencyinjectiontothatobject.ThisisanalternativetoresolvingtheobjectusinganyoftheothertechniquesavailablewithUnity.However,rememberthattheBuildUpmethodcannotinjectdependentobjectsintoconstructorparameters,becausetheobjecthasalreadybeencreated;itisnotcreatedbyUnity.

TheBuildUpmethodisusefulwhenyoudonothavecontroloftheconstructionofaninstance,butyoustillwantpropertyormethodcallinjectionperformed.Forexample,ASP.NETpages,WindowsCommunicationFoundation(WCF)applications,andXAMLcodeoftencreateinstancesofobjectsandpassareferencetoyourcode.TheBuildUpmethodwillusuallyreturntheoriginalobjectafterpassingitthroughthecontainer,althoughcontainerextensionsmayaddotherfeaturesthatcausethemethodtoreturnadifferentobjectthatistype-compatiblewiththeexistingobject.Forexample,aninjectionstrategymaycreateandreturnaproxyforanobjectoraderivedobjectinsteadoftheactualobject.

IfyouhavecreatedoraddedextensionstotheUnitycontainer,theseextensionscanaccessanduseanamethatyouspecifywhenyouexecutetheBuildUpmethod.Thisallowstheextensionstochangetheirbehavior,dependingonthevalueyouspecify.Forexample,theymayusethenametocontrolhowdependenciesareresolvedortocontrolfeaturessuchaseventwiringorinterception.Theactualbehaviordependsontheindividualextension.

TheBuildUpMethodOverloads

UsingtheBuildUpMethod




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using BuildUp to Wire Up Objects Not Created by the Container'%0AEntLib50_028b8060-a816-4e7b-a7ab-9a2a1b9168ab%0APlease provide details of the error you have located...%0A


UsingInjectionAttributes

OneofthemostusefulandpowerfultechniqueswhenusingUnityistotakeadvantageofdependencyinjectionfortheparametersofclassconstructorsandmethods,andforthevaluesofproperties.Thisapproachallowsyoutoresolveandpopulatetheentirehierarchyofobjectsusedinyourapplicationbasedontyperegistrationsandmappingsdefinedinthecontainer,withthesubsequentadvantagesthisoffers.

Youcanspecifyconstructor,property,andmethodcallinjectioninformationinconfigurationorbyaddingregistrationstothecontaineratruntime.Youcanalsoapplyattributestomembersofyourclasses.Whenyouresolvetheseclassesthroughthecontainer,Unitywillgenerateinstancesofthedependentobjectsandwireupthetargetclasswiththeseinstances.

Unityperformsconstructorinjectionautomaticallyonresolvedclasses,choosingthemostcomplexconstructorandpopulatinganyparametersforwhichyoudonotprovidevalueswhenitconstructstheobject.YoucanalsospecifywhichconstructorUnityshouldusetoconstructtheobject.Formoreinformation,seeAnnotatingObjectsforConstructorInjection.

Propertyandmethodcallinjectiondonotoccurautomaticallyunlessyouhaveregisteredinjectiontypesinthecontaineratdesigntimeorruntime.Ifyouhavenotregisteredinjectiontypesinthecontainer,youcanaddattributestothemembersofyourresolvedclasstoforceinjectionofdependentobjectswhenthetargetclassisresolved.Formoreinformation,seeAnnotatingObjectsforProperty(Setter)InjectionandAnnotatingObjectsforMethodCallInjection.

Forinformationaboutregisteringinjectiontypesintheconfigurationatdesigntimeorruntime,seeConfiguringUnity.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Injection Attributes'%0AEntLib50_d545e9f6-0bf5-4ebb-a5b5-7520f96d8a78%0APlease provide details of the error you have located...%0A


AnnotatingObjectsforConstructorInjection

Unitysupportsautomaticdependencyinjectionforclassconstructors.YoucanusetheUnitycontainertogenerateinstancesofdependentobjectsandwireupthetargetclasswiththeseinstances.Thistopicexplainshowtouseboththeautomaticconstructorinjectionmechanismandanattributeappliedtotheconstructorofaclasstodefinethedependencyinjectionrequirementsofthatclass.Theattributecanalsospecifyparametersthattheconstructorwillpasstothedependentobjectthatthecontainergenerates.

ToperforminjectionofdependentclassesintoobjectsyoucreatethroughtheUnitycontainer,youcanusethefollowingtechniques:

SingleConstructorAutomaticInjection.Withthistechnique,youallowtheUnitycontainertosatisfyanyconstructordependenciesdefinedinparametersoftheconstructorautomatically.Youusethistechniquewhenthereisasingleconstructorinthetargetclass.SpecifyingNamedTypeMappings.Withthistechnique,youspecifynamedmappingsfordependenciesintheparametersofaclassconstructor.Namedmappingsallowyoutospecifymorethanonemappingforaninterfaceorbaseclass,orforatyperegistration.MultipleConstructorInjectionUsinganAttribute.Withthistechnique,youapplyattributestotheclassconstructor(s)thatspecifythedependencies.Youusethistechniquewhenthereismorethanoneconstructorinthetargetclass.

Constructorinjectionisaformofmandatoryinjectionofdependentobjects,aslongasdevelopersusetheUnitycontainertogeneratethetargetobject.ThedependentobjectinstanceisgeneratedwhentheUnitycontainercreatesaninstanceofthetargetclassusingtheconstructor.Formoreinformation,seeNotesonUsingConstructorInjection.

CopyCode

CopyCode

SingleConstructorAutomaticInjectionForautomaticconstructorinjection,yousimplyspecifyasparametersoftheconstructorthedependentobjecttypes.Youcanspecifytheconcretetype,orspecifyaninterfaceorbaseclassforwhichtheUnitycontainercontainsaregisteredmapping.

Touseautomaticsingle-constructorinjectiontocreatedependentobjects1. Defineaconstructorinthetargetclassthattakesasaparameterthe

concretetypeofthedependentclass.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontainingaconstructorthathasadependencyonaclassnamedMyDependentClass.C#

publicclassMyObject

{

publicMyObject(MyDependentClassmyInstance)

{

//workwiththedependentinstance

myInstance.SomeProperty="SomeValue";

//orassignittoaclass-levelvariable

}

}

VisualBasic

PublicClassMyObject

PublicSubNew(myInstanceAsMyDependentClass)

'workwiththedependentinstance

myInstance.SomeProperty="SomeValue"

'orassignittoaclass-levelvariable

EndSub

EndClass

2. Inyourrun-timecode,usetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillinstantiatethedependentconcreteclassandinjectitintothetarget

CopyCode

class.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontainingaconstructorthathasadependencyonaclassnamedMyDependentClass.C#

IUnityContaineruContainer=newUnityContainer();

MyObjectmyInstance=uContainer.Resolve<MyObject>();

VisualBasic

DimuContainerAsIUnityContainer=NewUnityContainer()

DimmyInstanceAsMyObject=uContainer.Resolve(OfMyObject)()

3. Alternatively,youcandefineatargetclassthatcontainsmorethanonedependencydefinedinconstructorparameters.TheUnitycontainerwillinstantiateandinjectaninstanceofeachone.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontainingaconstructorthathasdependenciesontwoclassesnamedDependentClassAandDependentClassB.C#

publicclassMyObject

{

publicMyObject(DependentClassAdepA,DependentClassBdepB)

{

//workwiththedependentinstances

depA.SomeClassAProperty="SomeValue";

depB.SomeClassBProperty="AnotherValue";

//orassignthemtoclass-levelvariables

}

}

VisualBasic

PublicClassMyObject

CopyCode

PublicSubNew(depAAsDependentClassA,depBAsDependentClassB)


depA.SomeClassAProperty="SomeValue"

depB.SomeClassBProperty="AnotherValue"

'orassignthemtoclass-levelvariables

EndSub

EndClass

4. Inyourrun-timecode,usetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillcreateaninstanceofeachofthedependentconcreteclassesandinjectthemintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontainingaconstructorthathasconstructordependencies.C#



VisualBasic



5. Inadditiontousingconcretetypesasparametersofthetargetobjectconstructor,youcanuseinterfacesorbaseclasstypesandthenregistermappingsintheUnitycontainertotranslatethesetypesintothecorrectconcretetypes.Defineaconstructorinthetargetclassthattakesasparameterstheinterfaceorbasetypesofthedependentclass.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontainingaconstructorthathasadependencyonaclassthatimplementstheinterfacenamedIMyInterfaceandaclassthatinheritsfromMyBaseClass.C#

CopyCode

publicclassMyObject

{

publicMyObject(IMyInterfaceinterfaceObj,MyBaseClassbaseObj)

{

//workwiththeconcretedependentinstances

//orassignthemtoclass-levelvariables

}

}

VisualBasic

PublicClassMyObject

PublicSubNew(interfaceObjAsIMyInterface,baseObjAsMyBaseClass)


'orassignthemtoclass-levelvariables

EndSub

EndClass

6. Inyourrun-timecode,registerthemappingsyourequirefortheinterfaceandbaseclasstypes,andthenusetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillinstantiateaninstanceofeachofthemappedconcretetypesforthedependentclassesandinjectthemintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontainingaconstructorthathasadependencyonthetwoobjectsoftypeIMyInterfaceandMyBaseClass.C#

IUnityContaineruContainer=newUnityContainer()

.RegisterType<IMyInterface,FirstObject>()

.RegisterType<MyBaseClass,SecondObject>();


VisualBasic

DimuContainerAsIUnityContainer=NewUnityContainer()_

.RegisterType(OfIMyInterface,FirstObject)()_

.RegisterType(OfMyBaseClass,SecondObject)()


SpecifyingNamedTypeMappingsTheprecedingexampleshowshowyoucanresolvetypesforconstructorparametersusingthedefault(unnamed)mappingsinthecontainer.Ifyouregistermorethanonemappingforatype,youmustdifferentiatethembyusinganame.Inthiscase,youcanspecifywhichnamedmappingthecontainerwillusetoresolveeachconstructorparametertype.

Touseattributedconstructorinjectionwithnamedcontainertypemappings

1. Defineaconstructorinthetargetclassthattakesasaparametertheconcretetypeofthedependentclass,andapplyaDependencyattributetotheparameterthatspecifiesthenameoftheregisteredmappingtouse.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontainingaconstructorthathasadependencyonaserviceregisteredwiththenamemyDataService,andwhichimplementstheIMyServiceinterface.ItassumesthatthecontainercontainsamappingdefinedwiththenameDataServicebetweentheIMyServiceinterfaceandaconcreteimplementationofthisinterface.C#

publicclassMyObject

{

publicMyObject([Dependency("DataService")]IMyServicemyDataService)

{

//workwiththeservicehere

}

}

VisualBasic

PublicClassMyObject

PublicSubNew(<Dependency("DataService")>myDataServiceAsIMyService)

'workwiththeservicehere

EndSub

EndClass

CopyCode

2. Inyourrun-timecode,usetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillinstantiatethedependentconcreteclassdefinedinthemappingnamedDataServiceandinjectitintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassshownabove.C#



VisualBasic



YoucanusetheDependencyattributeonmorethanoneconstructorparameter.Youcanalsouseitwhentheconstructordefinesmorethanoneparameterofthesametypetodifferentiatethemappingsandensurethattheappropriateconcretetypeisreturnedforeachparameter.

Note:Ifyouspecifyanamedmappingandthereisnomappingregisteredforthattypeandname,thecontainerwillraiseanexception.

CopyCode

CopyCode

MultipleConstructorInjectionUsinganAttributeWhenatargetclasscontainsmorethanoneconstructorwiththesamenumberofparameters,youmustapplytheInjectionConstructorattributetotheconstructorthattheUnitycontainerwillusetoindicatewhichconstructorthecontainershoulduse.Aswithautomaticconstructorinjection,youcanspecifytheconstructorparametersasaconcretetype,oryoucanspecifyaninterfaceorbaseclassforwhichtheUnitycontainercontainsaregisteredmapping.

Touseattributedconstructorinjectionwhenthereismorethanoneconstructor

1. ApplytheInjectionConstructorattributetotheconstructorinthetargetclassthatyouwantthecontainertouse.Inthesimplestcase,thetargetconstructortakesasaparametertheconcretetypeofthedependentclass.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontainingtwoconstructors,oneofwhichhasadependencyonaclassnamedMyDependentClassandhastheInjectionConstructorattributeapplied.C#

publicclassMyObject

{

publicMyObject(SomeOtherClassmyObjA)

{

...

}

[InjectionConstructor]

publicMyObject(MyDependentClassmyObjB)

{

...

}

}

VisualBasic

CopyCode

PublicClassMyObject

PublicSubNew(myObjAAsSomeOtherClass)

...

EndSub

<InjectionConstructor()>_

PublicSubNew(myObjBAsMyDependentClass)

...

EndSub

EndClass

2. Inyourrun-timecode,usetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillinstantiatethedependentconcreteclassdefinedintheattributedconstructorandinjectitintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontaininganattributedconstructorthathasadependencyonaclassnamedMyDependentClass.C#



VisualBasic



3. Alternatively,youcandefineamultiple-constructortargetclassthatcontainsmorethanonedependencydefinedinthetargetconstructorparameters.TheUnitycontainerwillinstantiateandinjectaninstanceofeachone.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontaininganattributedconstructorthathasdependenciesontwoclasses,DependentClassAand

DependentClassB.C#

publicclassMyObject

{

publicMyObject(SomeClassAobjA,SomeClassBobjB)

{

...

}

[InjectionConstructor]

publicMyObject(DependentClassAdepA,DependentClassBdepB)

{

...

}

}

VisualBasic

PublicClassMyObject

PublicSubNew(objAAsSomeClassA,objBAsSomeClassB)

...

EndSub

<InjectionConstructor()>_

PublicSubNew(depAAsDependentClassA,depBAsDependentClassB)

...

EndSub

EndClass

4. Inyourrun-timecode,usetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillcreateaninstanceofeachofthedependentconcreteclassesdefinedinthe

CopyCode

attributedconstructorandinjectthemintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontainingaconstructorthathasconstructordependenciesC#



VisualBasic



5. Inadditiontousingconcretetypesasparametersofthetargetobjectconstructor,youcanuseinterfacesorbaseclasstypes,andthenregistermappingsintheUnitycontainertotranslatethesetypesintothecorrectconcretetypes.Fordetails,seesteps5and6oftheprocedureSingleConstructorAutomaticInjection.

NotesonUsingConstructorInjection




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Annotating Objects for Constructor Injection'%0AEntLib50_f173149f-03fc-4604-be5f-4f2a20ec470f%0APlease provide details of the error you have located...%0A

CopyCode


AnnotatingObjectsforProperty(Setter)Injection

Unitysupportsdependencyinjectiontosetthevaluesorpropertiesthroughattributesappliedtomembersofthetargetclass.YoucanusetheUnitycontainertogenerateinstancesofdependentobjectsandwireupthetargetclasspropertieswiththeseinstances.Thistopicexplainshowtouseanattributethatisappliedtooneormorepropertydeclarationsofaclasstodefinethedependencyinjectionrequirementsofthatclass.Theattributecanspecifyparametersfortheattributetocontrolitsbehavior,suchasthenameofaregisteredmapping.

ToperformpropertyinjectionofdependentclassesintoobjectsyoucreatethroughtheUnitycontainer,youapplytheDependencyattributetothepropertydeclarationsofaclass.TheUnitycontainerwillcreateaninstanceofthedependentclasswithinthescopeofthetargetobject(theobjectyouspecifyinaResolvemethodcall)andassignthisdependentobjecttotheattributedpropertyofthetargetobject.

Propertyinjectionisaformofoptionalinjectionofdependentobjects,aslongasdevelopersusetheUnitycontainertogeneratethetargetobject.Thedependentobjectinstanceisgeneratedbeforethecontainerreturnsthetargetobject.Inaddition,unlikeconstructorinjection,youmustapplytheappropriateattributeinthetargetclasstoinitiatepropertyinjection.YoucanalsoperformpropertyinjectionofoptionaldependentclassesbyapplyingtheOptionalDependencyattribute.Thissimplymarksadependencyasoptional,whichmeansthatthecontainerwilltrytoresolveit,andreturnnulliftheresolutionfailsratherthanthrowanexception.Formoreinformation,seeNotesonUsingProperty(Setter)Injection.

Touseproperty(setter)injectiontocreatedependentobjectsforaclass1. DefineapropertyinthetargetclassandapplytheDependency

attributetoittoindicatethatthetypedefinedandexposedbythepropertyisadependencyoftheclass.ThefollowingcodedemonstratespropertyinjectionforaclassnamedMyObjectthatexposesasapropertyareferencetoaninstanceofanotherclassnamedSomeOtherObject(notdefinedinthiscode).C#

publicclassMyObject

{

privateSomeOtherObject_dependentObject;

[Dependency]

publicSomeOtherObjectDependentObject

{

get{return_dependentObject;}

set{_dependentObject=value;}

}

}

VisualBasic

PublicClassMyObject

Private_dependentObjectAsSomeOtherObject

<Dependency()>_

PublicPropertyDependentObject()AsSomeOtherObject

Get

Return_dependentObject

EndGet

Set(ByValvalueAsSomeOtherObject)

_dependentObject=value

EndSet

EndProperty

EndClass

2. Inyourrun-timecode,usetheResolvemethodofthecontainertocreateaninstanceofthetargetclass,andthenreferencethepropertycontainingthedependentobject.TheUnitycontainerwillinstantiatethedependentconcreteclassdefinedintheattributedpropertyandinjectitintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontaininganattributedpropertythathasadependencyonaclass

CopyCode

CopyCode

namedSomeOtherObjectandthenretrievethedependentobjectfromtheDependentObjectproperty.C#



//nowaccessthepropertycontainingthedependency

SomeOtherObjectdepObj=myInstance.DependentObject;

VisualBasic



'nowaccessthepropertycontainingthedependency

DimdepObjAsSomeOtherObject=myInstance.DependentObject

3. Inadditiontousingconcretetypesforthedependenciesintargetobjectproperties,youcanuseinterfacesorbaseclasstypes,andthenregistermappingsintheUnitycontainertotranslatethesetypesintothecorrectconcretetypes.Defineapropertyinthetargetclassasaninterfaceorbasetype.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontainingpropertiesnamedInterfaceObjectandBaseObjectthathavedependenciesonaclassthatimplementstheinterfacenamedIMyInterfaceandonaclassthatinheritsfromMyBaseClass.C#

publicclassMyObject

{

privateIMyInterface_interfaceObj;

privateMyBaseClass_baseObj;

[Dependency]

CopyCode

publicIMyInterfaceInterfaceObject

{

get{return_interfaceObj;}

set{_interfaceObj=value;}

}

[Dependency]

publicMyBaseClassBaseObject

{

get{return_baseObj;}

set{_baseObj=value;}

}

}

VisualBasic

PublicClassMyObject

Private_interfaceObjAsIMyInterface

Private_baseObjAsMyBaseClass

<Dependency()>_

PublicPropertyInterfaceObject()AsIMyInterface

Get

Return_interfaceObj

EndGet

Set(ByValvalueAsIMyInterface)

_interfaceObj=value

EndSet

EndProperty

<Dependency()>_

PublicPropertyBaseObject()AsMyBaseClass

Get

Return_baseObj

EndGet

Set(ByValvalueAsMyBaseClass)

_baseObj=value

EndSet

EndProperty

EndClass

4. Inyourrun-timecode,registerthemappingsyourequirefortheinterfaceandbaseclasstypes,andthenusetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillcreateaninstanceofeachofthemappedconcretetypesforthedependentclassesandinjectthemintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontainingtwopropertiesthathavedependenciesonthetwoclassesnamedFirstObjectandSecondObject.C#





//nowaccessthepropertiescontainingthedependencies

IMyInterfacedepObjA=myInstance.InterfaceObject;

MyBaseClassdepObjB=myInstance.BaseObject;

VisualBasic





'nowaccessthepropertiescontainingthedependencies

DimdepObjAAsIMyInterface=myInstance.InterfaceObject

DimdepObjBAsMyBaseClass=myInstance.BaseObject

CopyCode

CopyCode

5. Youcanregistermultiplenamedmappingswiththecontainerforeachdependencytype,ifrequired,andthenuseaparameteroftheDependencyattributetospecifythemappingyouwanttousetoresolvethedependentobjecttype.Forexample,thefollowingcodespecifiesthemappingnamesfortheKeypropertyoftheDependencyattributefortwopropertiesofthesametype(inthiscase,aninterface)intheclassMyObject.C#

publicclassMyObject

{

privateIMyInterface_objA,_objB;

[Dependency("MapTypeA")]

publicIMyInterfaceObjectA

{

get{return_objA;}

set{_objA=value;}

}

[Dependency("MapTypeB")]

publicIMyInterfaceObjectB

{

get{return_objB;}

set{_objB=value;}

}

}

VisualBasic

PublicClassMyObject

Private_objA,_objBAsIMyInterface

<Dependency("MapTypeA")>_

PublicPropertyObjectA()AsIMyInterface

Get

Return_objA

EndGet


_objA=value

EndSet

EndProperty

<Dependency("MapTypeB")>_

PublicPropertyObjectB()AsIMyInterface

Get

Return_objB

EndGet


_objB=value

EndSet

EndProperty

EndClass

6. Inyourrun-timecode,registerthenamed(non-default)mappingsyourequireforthetwoconcretetypesthatthepropertieswilldependon,andthenusetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillinstantiateaninstanceofeachofthemappedconcretetypesforthedependentclassesandinjectthemintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontainingtwopropertiesthathavedependenciesonthetwoclassesnamedFirstObjectandSecondObject.C#


.RegisterType<IMyInterface,FirstObject>("MapTypeA")

.RegisterType<IMyInterface,SecondObject>("MapTypeB");


//nowaccessthepropertiescontainingthedependencies

IMyInterfacedepObjA=myInstance.ObjectA;

IMyInterfacedepObjB=myInstance.ObjectB;

VisualBasic


.RegisterType(OfIMyInterface,FirstObject)("MapTypeA")_

.RegisterType(OfIMyInterface,SecondObject)("MapTypeB")


'nowaccessthepropertiescontainingthedependencies

DimdepObjAAsIMyInterface=myInstance.ObjectA

DimdepObjBAsIMyInterface=myInstance.ObjectB

UsingOptionalDependencies

NotesonUsingProperty(Setter)Injection




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Annotating Objects for Property (Setter) Injection'%0AEntLib50_135fa151-4553-43bf-87c2-e71935a1075a%0APlease provide details of the error you have located...%0A


AnnotatingObjectsforMethodCallInjection

Unitysupportsdependencyinjectiontosetthevaluesofparametersofmethodsspecifiedthroughattributesappliedtomembersofthetargetclass.YoucanusetheUnitycontainertogenerateinstancesofdependentobjectsandwireupthetargetclassmethodparameterswiththeseinstances.Thistopicexplainshowtouseanattributethatisappliedtooneormoremethoddeclarationsofaclasstodefinethedependencyinjectionrequirementsofthatclass.

ToperforminjectionofdependentclassesintoobjectsyoucreatethroughtheUnitycontainer,youapplytheInjectionMethodattributetothemethoddeclarationsofaclass.TheUnitycontainerwillforcethetargetobject(theobjectyouspecifyinaResolvemethodcall)tocreateaninstanceofthedependentclassandthencallthetargetmethod.Ifrequired,yourcodeinthemethodcansavethisinstancebyassigningittoaclass-levelvariable.

MethodcallinjectionisaformofoptionalinjectionofdependentobjectsthatyoucanuseifyouusetheUnitycontainertogeneratethetargetobject.UnityinstantiatesdependentobjectsdefinedinparametersofmethodsthatcarrytheInjectionMethodattributewithinthescopeofthetargetobject.Thenitcallstheattributedmethodofthetargetobjectbeforereturningtheobjecttothecaller.YoumustapplytheInjectionMethodattributeinthetargetclasstoinitiatemethodcallinjection.Formoreinformation,seeNotesonUsingMethodCallInjection.

Tousemethodcallinjectiontocreatedependentobjectsforaclass1. DefineamethodinthetargetclassandapplytheInjectionMethod

attributetoittoindicatethatanytypesdefinedinparametersofthemethodaredependenciesoftheclass.Thefollowingcodedemonstratesthemostcommonscenario—savingthedependentobjectinstanceinaclass-levelvariable—foraclassnamedMyObjectthatexposesamethodnamedInitializethattakesasaparameterareferencetoaninstanceofanotherclassnamedSomeOtherObject(notdefinedinthiscode).C#

CopyCode

publicclassMyObject

{

privateSomeOtherObjectdependentObject;

[InjectionMethod]

publicvoidInitialize(SomeOtherObjectdep)

{

//assignthedependentobjecttoaclass-levelvariable

dependentObject=dep;

}

}

VisualBasic

PublicClassMyObject

PrivatedependentObjectAsSomeOtherObject

<InjectionMethod()>_

PublicSubInitialize(depAsSomeOtherObject)

'assignthedependentobjecttoaclass-levelvariable

dependentObject=dep

EndSub

EndClass

2. Inyourrun-timecode,usetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillinstantiatethedependentconcreteclassdefinedintheattributedmethod,injectitintothetargetclass,andexecutethemethod.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontaininganattributedmethodthathasadependencyonaclassnamedSomeOtherObject.C#



VisualBasic



3. Inadditiontousingconcretetypesforthedependenciesintargetobjectmethods,youcanuseinterfacesorbaseclasstypesandthenregistermappingsintheUnitycontainertotranslatethesetypesintotheappropriateconcretetypes.Defineamethodinthetargetclassthattakesasparametersinterfacesorbasetypes.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontainingamethodnamedInitializethattakesasparametersanobjectnamedinterfaceObjthatimplementstheinterfacenamedIMyInterfaceandanobjectnamedbaseObjthatinheritsfromtheclassMyBaseClass.C#

publicclassMyObject

{

privateIMyInterfacedepObjectA;

privateMyBaseClassdepObjectB;

[InjectionMethod]

publicvoidInitialize(IMyInterfaceinterfaceObj,MyBaseClassbaseObj)

{

depObjectA=interfaceObj;

depObjectB=baseObj;

}

}

VisualBasic

PublicClassMyObject

CopyCode

PrivatedepObjectAAsIMyInterface

PrivatedepObjectBAsMyBaseClass


PublicSubInitialize(interfaceObjAsIMyInterface,baseObjAsMyBaseClass)

depObjectA=interfaceObj

depObjectB=baseObj

EndSub

EndClass

4. Inyourrun-timecode,registerthemappingsyourequirefortheinterfaceandbaseclasstypes,andthenusetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillinstantiateaninstanceofeachofthemappedconcretetypesforthedependentclasses,andinjectthemintothetargetclass.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampletargetclassnamedMyObjectcontaininganattributedmethodthathasdependenciesonthetwoclasses,FirstObjectandSecondObject.C#





VisualBasic





SpecifyingNamedTypeMappingsTheprecedingexampleshowshowyoucanresolvetypesformethodparametersusingthedefault(unnamed)mappingsinthecontainer.Ifyouregistermorethanonemappingforatype,youmustdifferentiatethembyusinganame.Inthiscase,youcanspecifywhichnamedmappingthecontainerwillusetoresolvethemethodparametertypes.

Touseattributedmethodcallinjectionwithnamedcontainertypemappings

1. Defineamethodinthetargetclassthattakesasaparametertheconcretetypeofthedependentclass,andapplyaDependencyattributetotheparameterthatspecifiesthenameoftheregisteredmappingtouse.Forexample,thefollowingcodeshowsatargetclassnamedMyObjectcontainingamethodnamedInitializethathasadependencyonaservicethatimplementstheIMyServiceinterface.ThecodeassumesthatthecontainercontainsamappingdefinedwiththenameDataServicebetweentheIMyServiceinterfaceandaconcreteimplementationofthatinterface.C#

publicclassMyObject

{

privateIMyServicemyDataService;

[InjectionMethod]

publicvoidInitialize([Dependency("DataService")]IMyServicetheService)

{

//assignthedependentobjecttoaclass-levelvariable

myDataService=theService;

}

}

VisualBasic

PublicClassMyObject

CopyCode

PrivatemyDataServiceAsIMyService


PublicSubInitialize(<Dependency("DataService")>theServiceAsIMyService)

'assignthedependentobjecttoaclass-levelvariable

myDataService=theService

EndSub

EndClass

2. Inyourrun-timecode,usetheResolvemethodofthecontainertocreateaninstanceofthetargetclass.TheUnitycontainerwillinstantiatethedependentconcreteclassdefinedintheattributedmethod,injectitintothetargetclass,andexecutethemethod.Forexample,thefollowingcodeshowshowyoucaninstantiatetheexampleclassshownabove.C#



VisualBasic



Note:Ifyouspecifyanamedmappingandthereisnomappingregisteredforthattypeandname,thecontainerwillraiseanexception.

NotesonUsingMethodCallInjection




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Annotating Objects for Method Call Injection'%0AEntLib50_f6bbc4ca-d485-4129-89e1-1380ce97f27c%0APlease provide details of the error you have located...%0A

CopyCode

CopyCode


CircularReferenceswithDependencyInjection

Dependencyinjectionmechanismscarrytheriskofunintentionalcircularreferences,whicharenoteasytodetectorprevent.Thistopicdescribesthesituationswhereyoumayinadvertentlycausecircularreferencestooccur,resultinginastackoverflowandapplicationerror.Themostcommoncausesofcircularreferenceswithdependencyinjectionarethefollowing:

ObjectsgeneratedthroughconstructorinjectionthatreferenceeachotherintheirconstructorparametersObjectsgeneratedthroughconstructorinjectionwhereaninstanceofaclassispassedasaparametertoitsownconstructorObjectsgeneratedthroughmethodcallinjectionthatreferenceeachotherObjectsgeneratedthroughproperty(setter)injectionthatreferenceeachother

Forexample,thefollowingcodeshowstwoclassesthatreferenceeachotherintheirconstructors.C#

publicclassClass1

{

publicClass1(Class2test2)

{...}

}

publicclassClass2

{

publicClass2(Class1test1)

{...}

}

VisualBasic

PublicClassClass1

PublicSubNew(test2AsClass2)

...

EndSub

EndClass

PublicClassClass2

PublicSubNew(test1AsClass1)

...

EndSub

EndClass

Itistheresponsibilityofthedevelopertopreventthistypeoferrorbyensuringthatthemembersofclassestheyusewithdependencyinjectiondonotcontaincircularreferences.

Note:Youcoulduseconstructorinjectiontospecifyanyofaseriesofconstructorsormethodoverloads;however,youcouldinadvertentlycauseendlessrecursion.Toavoidtheendlessrecursion,specifywhichconstructortocallintheRegisterTypecall.

Unity'sdefaultbehavioristoresolvetheconstructorwiththemostparameters.Thiswouldcauseendlessrecursioninthefollowingexample.C#

container.RegisterType<IServiceProvider,ServiceContainer>();

varsp=container.Resolve<IServiceProvider>();

VisualBasic

container.RegisterType(OfIServiceProvider,ServiceContainer)()

Dimsp=container.Resolve(OfIServiceProvider)()

Toavoidtheendlessrecursion,specifywhichconstructortocallintheRegisterTypecall,asinthefollowingexample:

C#

container.RegisterType<IServiceProvider,ServiceContainer>(newInjectionConstructor());

VisualBasic

container.RegisterType(OfIServiceProvider,ServiceContainer)_

(NewInjectionConstructor())

Inthiscase,whencreatingtheservicecontainer,thezeroargumentconstructorisexplicitlyrequested.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Circular References with Dependency Injection'%0AEntLib50_567330c5-a09a-4c40-8dcf-1c0ceb5f3198%0APlease provide details of the error you have located...%0A


InterceptionwithUnity

Unityinterceptionenablesyoutoeffectivelycapturecallstoobjectsandaddadditionalfunctionalitytothetargetobject.Interceptionisusefulwhenyouwanttomodifythebehaviorforindividualobjectsbutnottheentireclass,verymuchasyouwoulddowhenusingtheDecoratorpattern.Itprovidesaflexibleapproachforaddingnewbehaviorstoanobjectatruntime.

Thissectioncontainsthefollowingtopicsthatwillhelpyoutounderstandinterception:

AboutUnityInterception.ThissectionofthistopicdescribesthebasicprinciplesofinterceptioninUnity.ScenariosforInterception.ThistopicdescribescommonscenariosaddressedbyUnityinterception.BehaviorsforInterception.ThistopicdescribesbehaviorsyoumightimplementwiththeIInterceptionBehaviorinterfacetoconfigureacontainerthroughtheRegisterTypemethod.ConfiguringaContainerforInterception.ThistopicdescribeshowtoconfiguretheUnitycontainerforinterception.UnityInterceptionTechniques.ThistopicdescribesindetailthedesignofUnityinterception.UsingInterceptioninApplications.ThistopicdescribeshowyouuseUnityinterceptioninyourapplications.UsingInterceptionandPolicyInjection.ThistopicexplainshowpolicyinjectionthroughinterceptionworksinUnity,howyoucanusematchingrulestoselecttargetclassesandclassmembersforpolicyinjection,andhowyoucanusetheEnterpriseLibrarycallhandlerswithUnity.

http://en.wikipedia.org/wiki/Decorator_pattern

AboutUnityInterceptionToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Interception with Unity'%0AEntLib50_8354c203-e77a-4873-80c9-b9041b468795%0APlease provide details of the error you have located...%0A


ScenariosforInterception

Unityinterceptionaddressesthefollowingscenarios:Addingresponsibilitiestoindividualobjectsandnottheentireclassandavoidingastaticsolution,muchasinadecoratorpattern.Inamannersimilartothewayadecoratorforwardsrequeststotheobjectandenablesyoutoperformadditionalactionsbeforeorafterforwardingtherequest,interceptioninterceptsthecalltothetargetobjectanddynamicallyaddsbehaviorstoindividualobjectswithoutaffectinganyotherobjects.Thiscanbeusefulinmanagingcrosscuttingconcernsthataccesscommonfeaturessuchasloggingorvalidation.Toaugmentormodifythebehaviorfromexistingclassesthatyoucannotmodify,providedthattheyareinterceptablebytheavailableinterceptionmechanisms.Enablingthedeveloperandadministratortoconfigurethebehaviorofobjectsinanapplicationthroughconfigurationwhenusedinconjunctionwithadependencyinjection(DI)container,byaddingorremovingbehaviorsthatexecutecommontasksoraddcustomfeatures.Enablingthedeveloperandadministratortocapturecallstoobjectsandaddorremovebehaviorsthatexecutecommontasksoraddcustomfeaturesatruntime,butinthiscaseindependentofaDIcontainer.Minimizingtheworkrequiredandthecodethatthedevelopermustwritetoperformcommontaskswithinanapplication,suchaslogging,validation,authorization,andinstrumentation.Reducingdevelopmenttimeandcost,andminimizingbugsincomplexapplicationsthatusecommonandsharedtasksandservices.

BenefitsofUsingUnityInterception

LimitationsofUnityInterception

AlternativestoUsingUnityInterception

http://www.springframework.net/




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Scenarios for Interception'%0AEntLib50_ed7289ac-2407-409a-8a4d-04bc2a0c763a%0APlease provide details of the error you have located...%0A


BehaviorsforInterception

Interceptionisbasedonabehaviororseriesofbehaviorsinthebehaviorspipelinethatdescribewhattodowhenanobjectisintercepted.Unityprovidesabuilt-indefaultpolicyinjectionbehaviortofacilitatetheimplementationofpolicyinjection.Thepolicyinjectionbehaviorattachesorinjectssomefunctionalitytospecificmethodsbyusingcallhandlersandmatchingrulesonaper-methodbasis.FormoreinformationonpolicyinjectionseeUsingInterceptionandPolicyInjection.

YoucanalsocreateyourowncustombehaviorsbyimplementingtheIInterceptionBehaviorinterface.Theinterceptionbehaviorsareaddedtoapipelineandarecalledforeachinvocationofthatpipeline.Youhavewidelatitudeinwhatfunctionalityyoudesignforyourbehavior.Somepracticalusesofbehaviorsincludeimplementingcustomtasksandbusinessrules,implementingINotifyPropertyChangedtosupportapropertychangeevent,toprovidesupportfortheErrorProvider/IDataErrorInfoapproachtovalidationinWindows®PresentationFoundation(WPF),andtoimplementaMockingframework.

Customtasksandbusinessrulesyoumightchosetoimplementwithindividualcustombehaviorswouldincludetaskssuchasvalidatingparametersorauthorizingusers.

WhenimplementingaWPFviewmodel,inordertogetthepropertychangeeventactionyoumustimplementINotifyPropertyChanged.Ratherthanimplementingthiseverytime,youcancreateabehaviorthataddsandimplementstheinterface.

Thereisnobuilt-insupportfortheErrorProvider/IDataErrorInfoapproachtovalidationinWPF;hencethereisnoErrorProvidercomponentinWPFeither.YoumustcreateanErrorProviderforuseinWPFapplications.TheDataGrid(1.1)andDataGridView(2.0)inWindowsFormsbothautomaticallydetectedthepresenceofthisinterfaceonobjectstheywereboundto,andshowedanyerrorswithoutanywork.TheWindowsFormsErrorProvidercouldbeusedtoautomaticallydisplayerrorsonanycontrolthatcamefromtheobjectsthey(andtheErrorProvider)wereboundto,allwithoutanyextracodebeingwritten.YoucanuseIDataErrorInfototakeadvantageofthevalidationworkinthe

.NETFramework.YoucanimplementIDataErrorInfoinaclassandbindtheclassconcreteobjecttotheDataGridViewcontrolthroughtheBindingsourceproperty.ThenusetheValidationApplicationBlocktovalidatetheclassobjectandstoretheresultsforeachproperty.

Implementingamockingframeworkthroughaninterceptionbehaviorcouldbeusefulincaseswherethecoderequiresaninterfacethathasnoimplementation.Thebehaviorcangiveyouamockupinterface.Youcoulduseamockingframeworktoimplementamockdatabase,mocklogger,ormockbuildercontext.

Thefollowingtopicsexplainordemonstrateinterceptionbehaviorsinmoredetail:

CustomInterceptionBehaviorsImplementIDataErrorInfoExample

CustomInterceptionBehaviors

ImplementINotifyPropertyChangedExampleToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Behaviors for Interception'%0AEntLib50_73690eea-cce2-48aa-a143-d6fcd80e1654%0APlease provide details of the error you have located...%0A


ConfiguringaContainerforInterception

Youcanuseinterceptionwithorwithoutadependencyinjection(DI)containersuchasUnity.UsingaDIcontainerrelievesyouoftheneedtomanuallycreateallthedependenciesandpassthemintothecorrectobjects.IfyouchoosetousetheUnityDIcontainer,youcanconfigurethecontainerbyusingaconfigurationfileoratruntimebyusingtheAPI.

InUnity,interceptionisjustanotherextensionpointinsteadofaself-containedpartoftheconfigurationfile,asinpreviousversions.PriortoUnity2.0whenyouspecifiedinterception,policyinjectionwasimplicitlyconfiguredbytheunderlyingcode.Wherethebehaviorofinterceptionwasimplicitbefore,itisexplicitnow;youspecifythatinterceptionistohappenandyouspecifywhatistohappenuponinterception.Interceptionbecomesjustonemorethingthatyoucandescribeabouthowanobjectisresolved.Unityversion2.0enablesyoutomodifyhowinterceptionhappensandhowtheobjectiscreated.

TherearetwoapproachesforsettingupUnityinterception:TheapproachintroducedinUnity2.0inwhichinterceptionisconfiguredasjustanotherextensionpointelementintheentryforacontainertype.Configureanextensionpointbyusingthe<sectionExtension>and<extension>tagsintheconfigurationfileorbyusingtheRegisterTypemethodatruntime.Thepre-Unity2.0approachusedinearlierversionsofUnityinwhichinterceptionisaself-containedpartofthecontainerconfiguredbyusingtheinterceptionextensionelements,<extensionConfig>and<interceptors>intheconfigurationfileorbyusingtheSetInterceptorFororSetDefaultInterceptorFormethodsontheinterceptioncontainerextension.Thisearlierstyleisstillavailableprimarilyforbackwardcompatibility.

Youcanuseaconfigurationfiletospecifyacontainer-createdbehaviorwithanylogicalconfiguration.Fordetailedinterceptionschemainformation,seeConfigurationFilesforInterception.

Thistopiccontainsthefollowingsectionstodescribehowtoconfigureacontainerforinterception:

AddingtheInterceptionExtensiontotheContainerConfiguringInterceptionofaTypeMoreInformation

AddingtheInterceptionExtensiontotheContainer

ConfiguringInterceptionofaType




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Configuring a Container for Interception'%0AEntLib50_6a974ef0-4f5e-407f-b196-b126a08f9205%0APlease provide details of the error you have located...%0A


UnityInterceptionTechniques

Inordertoperforminterception,Unitymustbeabletocapturetheoriginalcallandpassitthroughabehaviorspipelinetothetargetobject,thenpasstheresultbackthroughthebehaviorspipelinetotheoriginalcaller.Thetwocommonapproachestotheinterceptionprocessareinstanceinterceptionandtypeinterception,andUnityprovidestechniquesforboth.Instanceinterceptorsworkbycreatingaproxytotheinterceptedinstance.Typeinterceptorsworkbyderivinganewtypethatimplementsinterception.Theinstanceinterceptiontargetistheoriginal,non-interceptedobject,butwhenperformingtypeinterceptionthetargetisinterceptedandaderivedobjectused.

Note:Instanceinterceptionworksonlyoninstancemethods;itdoesnotworkforstaticmethodsorconstructorssincetheconstructorhasalreadyexecutedbythetimetheclientcodegetsbackaninterception-readyobject.Instanceinterceptioncanonlyinterceptpublicinstancemethods.Typeinterceptioncaninterceptpublicandprotectedmethods.

Thistopiccontainsthefollowingsectionsthatwillhelpyoutounderstandinterception:

InstanceInterceptionTypeInterceptionComparisonofInterceptionTechniquesSummaryofInterceptionApproaches

InstanceInterceptionInstanceinterceptionworkswithbothexistinginstancesofobjects,andwithnewinstancescreatedbyUnity.Thefollowingschematicshowsthebasicprocessofinstanceinterception.

WhentheapplicationresolvestheobjectthroughtheUnitycontainer,theUnityinterceptioncontainerextensionmanagestheprocess.Itobtainsaneworexistinginstanceoftheobjectfromthecontainer,andcreatesaproxytotheobject.Thenitcreatesthehandlerpipelineandconnectsittothetargetobjectbeforereturningareferencetotheproxy.Theclientthencallsmethodsandsetspropertiesontheproxyasthoughitwerethetargetobject.

Note:UnityinterceptioncanbeusedwithoutaUnityDIcontainerbyusingthestand-aloneAPIthroughthestaticInterceptclass.Formoreinformation,seeUsingInterceptioninApplications.

Thesecallspassthroughtheinterceptionbehaviors,executingthepreprocessingstageofeachone,withthefinalbehaviorinthechainpassingthecalltothetargetobject.Thereturnvaluefromthetargetobjectpassesbackthroughthebehaviorsinthereverseorder,executingthepost-processingstageofeachone.Thefirstbehaviorinthepipelinethenpassestheresultbacktothecaller.

Instanceinterceptionisthemostcommonandwidelyusedtechnique.ItcanbeusedwithobjectsthateitherimplementtheMarshalByRefObjectabstractclass,orimplementapublicinterfacethatdefinesallofthemethodstobeintercepted.Unityprovidesthetwointerceptors,TransparentProxyInterceptorandInterfaceInterceptor,thatsupportthesetwoscenarios.Formoredetails,seethetablesinComparisonofInterceptionTechniqueslaterinthistopic.

TypeInterceptionTypeinterceptionusesaderivedclassinsteadofaproxy.Asdescribedintheprevioussection,instanceinterceptionworksbycreatingaproxytothetargetobject.Typeinterception,ontheotherhand,morecloselyresemblesaspect-orientedprogramming(AOP)techniquescommoninJava-basedsystems.Typeinterceptionavoidsthepossibleperformancepenaltiesofusingaproxyobjectbydynamicallyderivinganewclassfromtheoriginalclass,andinsertingcallstothebehaviorsthatmakeupthepipeline.Thefollowingschematicshowsthebasicprocessoftypeinterception.

WhentheapplicationresolvestherequiredtypethroughtheUnitycontainer,theUnityinterceptioncontainerextensioncreatesthenewderivedtypeandpassesit,ratherthantheresolvedtype,backtothecaller.Becausethetypepassedtothecallerderivesfromtheoriginalclass,itcanbeusedinthesamewayastheoriginalclass.Thecallersimplycallstheobject,andthederivedclasswillpassthecallthroughthebehaviorsinthepipelinejustasisdonewhenusinginstanceinterception.

Note:

UnityinterceptioncanbeusedwithoutaUnityDIcontainerbyusingthestand-aloneAPIthroughthestaticInterceptclass.Formoreinformation,seeUsingInterceptioninApplications.

However,duetothenatureofthedynamictypegeneration,therearesomelimitationswiththisapproach.Itcanonlybeusedtointerceptpublicandprotectedvirtualmethods,andcannotbeusedwithexistingobjectinstances.Ingeneral,typeinterceptionismostsuitedtoscenarioswhereyoucreateobjectsespeciallytosupportinterceptionandallowfortheflexibilityanddecouplingprovidedbypolicyinjection,orwhenyouhavemappingsinyourcontainerforbaseclassesthatexposevirtualmethods.Formoredetails,seethetablesofcomparisonsinthefollowingtopicComparisonofInterceptionTechniques.

ComparisonofInterceptionTechniquesTheprevioussectionsdemonstratedhowitisimportanttochoosetheappropriateinterceptiontechniquebasedonyourrequirementsandthetypeofobjectyouwanttointercept.ThefollowingtableliststhethreeinterceptorclassesincludedinUnity,anddescribeswhenyoushoulduseeachtype.

Type Description Use

TransparentProxyInterceptor

Aninstanceinterceptor.Theproxyiscreatedbyusingthe.NETTransparentProxy/RealProxyinfrastructure.

WhenthetypetointerceptisaMarshalByRefObjectorwhenonlymethodsfromthetype'simplementedinterfacesneedtobeintercepted.

InterfaceInterceptor

Aninstanceinterceptor.Itcanproxyonlyoneinterfaceontheobject.Itusesdynamiccodegenerationtocreatetheproxyclass.

Whenresolvinganinterfacemappedtoatype.

VirtualMethodInterceptor

Atypeinterceptor.Itusesdynamiccodegenerationtocreateaderivedclassthatisinstantiatedinsteadoftheoriginalinterceptedclass,andtohookupthebehaviors.

Whenonlyvirtualmethodsneedtobeintercepted.

Selectionofaspecificinterceptordependsonyourspecificneeds,becauseeachonehasvarioustradeoffs.Thefollowingtablesummarizesthethreeinterceptorsandtheiradvantagesanddisadvantages.

Type Advantages Disadvantages

TransparentProxyInterceptor

Caninterceptallmethodsofthetargetobject(virtual,non-virtual,orinterface).

TheobjectmusteitherimplementaninterfaceorinheritfromSystem.MarshalByRefObjectIfthemarshalbyreference

objectisnotabaseclass,youcanonlyproxyinterfacemethods.TheTransparentProxyprocessismuchslowerthanaregularmethodcall.

InterfaceInterceptor

Allowsinterceptiononanyobjectthatimplementsthetargetinterface.ItismuchfasterthantheTransparentProxyInterceptor.

Itonlyinterceptsmethodsonasingleinterface.Itcannotcastaproxybacktothetargetobject'sclassortootherinterfacesonthetargetobject.

VirtualMethodInterceptor

CallsaremuchfasterthantheTransparentProxyInterceptor.

Interceptiononlyhappensonvirtualmethods.Youmustsetupinterceptionatobjectcreationtimeandcannotinterceptanexistingobject.

SummaryofInterceptionApproachesUnityprovidesinstanceandtypeinterceptionwithinterceptedobjectsforwhichyouhaveobtainedareferenceeitherthroughthecontainer,orbyusingthestand-aloneAPItoexplicitlyinterceptaknowninstance.Instanceinterceptorsuseaseparateproxyobjectbetweenyourcodeandyourtargetobject.Usinginterception,youmakeacallontheproxyobjectinsteadofdirectlycallingthetargetobject.Theproxyinvokesthevariousinterceptionbehaviors,andthenitforwardsthecalltothetargetobject.Differentimplementationsofinstanceinterceptorscanhavedifferentconstraints.Instanceinterceptorshavethefollowingcharacteristics:

Theycaninterceptobjectscreatedbythecontainer.Theycaninterceptobjectsnotcreatedbythecontainer.TheTransparentProxyInterceptorcaninterceptmorethanoneinterface,andmarshal-by-referenceobjects.TheInterfaceInterceptorcanonlybeusedtointerceptasingleinterface.

Typeinterceptorscreateanewtypethatinheritsfromthetargettype.Thisnewtypeistheninstantiatedinsteadoftheoriginaltypeyourequested.Thenewtypeoverridesallthevirtualmethodsontheoriginaltargettype.Typeinstanceinterceptorshavethefollowingcharacteristics:

Onlyoneobjectiscreated;thereisnoproxyobjectbetweenthecallerandthenewobject.Thenewobjecthasfulltypecompatibilitybecauseitisderivedfromthetargettype.Theyareabletointerceptobjectsonlyatcreation,andcannotinterceptexistinginstances.Theycanonlyinterceptvirtualpublicandprotectedmethods.

ThesystemthatUnityusestoautomaticallycreateaderivedtargetobject,oraproxyandbehaviorspipeline,issimilartotheaspect-orientedprogramming(AOP)approach.However,UnityisnotanAOPframeworkimplementationforthefollowingreasons:

Itusesinterceptiontoenableonlypreprocessingbehaviorsandpost-processingbehaviors.Itdoesnotinsertcodeintomethods,althoughitcancreatederived

classescontainingpolicypipelines.Itdoesnotprovideinterceptionforclassconstructors.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Unity Interception Techniques'%0AEntLib50_9765b670-328a-488c-a219-d114381b7c75%0APlease provide details of the error you have located...%0A


UsingInterceptioninApplications

ThistopicdescribeshowtouseUnityinterceptioninyourapplications.YoucanuseUnityinterceptionwithadependencyinjection(DI)containerorasastand-alonefeaturewithnoDIcontainer.

WhenyouuseaDIcontainer,thecontainerprovidesareferencetotheinterceptedobject.Whenthecontainerresolvesanobjectthatisconfiguredforinterception,theobjectisinterceptedasdefinedintheconfiguration.Whenperformingstand-aloneinterception,youmustalreadyhaveareferencetotheobjectyouwantintercepted.Youinvokethestand-aloneinterceptionAPIandexplicitlyintercepttheobject.Formoreinformationonusingcontainers,seeDependencyInjectionwithUnity.

Unityinterceptionrequiresaninterceptor,andacollectionofinterception

behaviorsthatcompriseapipeline.Interceptorsareusedwhenperforminginterceptionthroughthecontainerandthroughthestand-aloneAPI.Usingthecontainerresultsinaddinginterceptionobjectsthatarebeingresolved,whileusingthestand-aloneAPIenablesyoutoperformjustinterception.

Inbothcasesyoucanimplementadditionalinterfacesoninterceptedobjects.Youmustprovidetheinformationfortheadditionalinterfacesthatwillbeaddedforinterception.Usingadditionalinterfaceshassomelimitations.Youcannotaddopengenericinterfacesandyoucannotreimplementaninterfacethathasalreadybeenimplementedwithnonvirtualmethods.Additionalinterfacesaresupportedbyallthreetypesofinterceptors.Whenyouareperforminginterfaceinterception,youcanonlyinvokemethodsontheparticularinterfaceyouusedtointerceptandanyadditionalinterfacesthatyouhavespecified.Caststootherinterfacesimplementedbytheinterceptedobjectwillfail.

Thoughbehaviorsnormallycanhavebothpre-andpost-processingfunctionality,withanyadditionalinterfacesthebehaviorsmusthandletheprocessinginitsentirety.Therecannotbeanypost-processingbecausetheoriginalobjecthasnoimplementationfortheadditionalinterfaces’methods.AnycallstotheadditionalinterfacemethodshandledbythebehaviorswillresultinaNotImplementedExceptionbeingthrown.

Youcanalsointerceptabstractclasseswithabstractmethods,allowingthebehaviorspipelinetoprovidetheimplementationfortheseabstractmethods.Thisissimilartoaddinginterfacesinthatinbothcasesthereareundefinedmethodsforwhichanimplementationmustbeprovided,buttheyaredifferentmechanisms.AbstractclassinterceptiononlyworkswiththeVirtualMethodInterceptor.Youcanimplementabstractclasseswithabstractmethods.Ifyouinterceptatypethatalreadyimplementssomeinterfaces,bothvirtualmethodandtransparentproxyinterceptionallowforcastingtotheseinterfacesandinvokemethodsonthem,whichwillbeintercepted.Therecannotbeanypostprocessingbecausetheoriginalobjecthasnoimplementationfortheadditionalinterfaces’methods

Thistopiccontainsthefollowingsections:Stand-aloneUnityInterceptiondescribeshowtouseUnityinterceptionasastand-alonefeature.InterceptionBehaviorPipelinedescribeshowtoaddabehaviorandinterceptortoanewinterceptionbehaviorspipeline.

InterceptionwithaContainerdescribesinterceptionwithacontainer.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Interception in Applications'%0AEntLib50_67c6df4d-4c1b-4020-82c8-f2cf87defbc2%0APlease provide details of the error you have located...%0A


Stand-aloneUnityInterception

YoucanuseUnityinterceptionasastand-alonefeaturewithnodependencyinjectioncontainerbyusingtheInterceptclass.Aswithacontainer,interceptionasastand-alonefeatureenablesyoutoperforminstanceortypeinterception.TheInterceptclasscontainstheNewInstance,NewInstanceWithAdditionalInterfaces,ThroughProxy,andThroughProxyWithAdditionalInterfacesmethods,enablingyoutoperformeitherproxyorinstanceinterception.AndbothmethodsincludetheAdditionalInterfacesparameter,enablingyoutoimplementadditionalinterfacesonthetargetobject.ThiscorrespondstotheAdditionalInterfacefeaturewhenusinginterceptionwithacontainer.Note:

ThefirstparameteronIntercept.ThroughProxy,Intercept.ThroughProxyWithAdditionalInterfacesandIntercept.NewInstanceisthecorrespondinginterceptorwhensettingupinterceptionthroughthestand-aloneAPI.

TheAdditionalInterfacesparameterontheobjectenablesyoutoreceivemoremessagesandtoaugmentthesetofmethodstheobjectcanrespondto.

Thissectioncontainsthefollowingsectionsdescribingstand-aloneinterception:Stand-AloneInterceptionwithaProxydescribescreatingaproxytotheinterceptedinstance.Stand-AloneInterceptionwithaDerivedTypedescribesinterceptionbyusingaderivedtype.

Stand-AloneInterceptionwithaProxy

Stand-aloneInterceptionwithaDerivedTypeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Stand-alone Unity Interception'%0AEntLib50_29f44713-c61a-4b7c-a21e-9cd4d183ace3%0APlease provide details of the error you have located...%0A

CopyCode

CopyCode

CopyCode


InterceptionBehaviorPipeline

Youmustaddbehaviorstothebehaviorpipelinetousethem.Thepipelinemaintainsalistofinterceptionbehaviorsandmanagesthem,callingthemintheproperorderwiththecorrectinputs.

Thefollowingexampleaddsabehaviorandinterceptortoanewinterceptionbehaviorspipeline.

Firstcreateaninterceptionbehaviorspipeline.C#

privateInterceptionBehaviorPipelinepipeline=newInterceptionBehaviorPipeline();

VisualBasic

PrivatepipelineAsNewInterceptionBehaviorPipeline()

Thenaddaninterceptionbehaviortothepipeline.C#

pipeline.Add(interceptor);

VisualBasic

pipeline.Add(interceptor)




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Interception Behavior Pipeline'%0AEntLib50_7f7a1362-150a-417c-8b15-ba4f7d08cd5a%0APlease provide details of the error you have located...%0A


InterceptionwithaContainer

TheUnitycontainerextensionenablesyoutoconfigureacontainerforinterception.Youcanusethecontainerconfigurationtodeterminewhetheranobjectshouldbeintercepted,whichmechanismshouldbeusedtoperformtheinterception,andwhattodowhentheobjectisintercepted.ItalsoprovidesaconvenientsetofmethodsforconfiguringinjectionforMicrosoft.Practices.Unity.InterceptionExtension.RuleDrivenPolicyinstances.

FormoreinformationaboutconfiguringacontainerseeConfiguringaContainerforInterceptionandConfiguringUnity.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Interception with a Container'%0AEntLib50_20b2c058-da8b-43ba-b0b5-40d919915481%0APlease provide details of the error you have located...%0A


UsingInterceptionandPolicyInjection

PolicyinjectionbyacombinationofUnityandthepatterns&practicesEnterpriseLibraryusesasetofcallhandlersandtheequivalentcallhandlerattributesinconjunctionwiththeunderlyingUnityinterceptionmechanism.Interceptionenablesyoutoeffectivelycapturecallstoobjectsandprovideadditionalfunctionalitytothetargetobjectbyusingbehaviorsandcallhandlersinthepipelinetodefineandmanagetheresultsoftheinterception.InEnterpriseLibrary,policyinjectionisjustoneimplementationofaUnityinterceptionbehavior.ThePolicyInjectionBehaviorcapturescallstoobjectsyouresolvethroughthecontainer,andappliesapolicythatusescallhandlersandmatchingrulesinheritedfromUnitytodefineitspolicyinjectionbehavioronaper-methodbasis.

Typically,youwillusethistechniquetochangethebehaviorofexistingobjects,ortoimplementthemanagementofcrosscuttingconcernsthroughreusablehandlers.Youcanspecifyhowtomatchthetargetobjectusingawiderangeofmatchingrules,andconstructabehaviorwhichiseffectivelyapolicypipelinethatcontainsoneormorecallhandlers.

Callstotheinterceptedmethodsorpropertiesofthetargetobjectarepassedthroughthecallhandlersintheorderinwhichyouaddthemtothepipeline,andreturnedthroughtheminthereverseorder.Yourcallhandlerscanaccessthevaluesinthecall,changethesevalues,andcontrolexecutionofthecall.Forexample,thecallhandlersmightauthorizeusers,validateparametervalues,cachethereturnvalue,and,ifthelogicsodictates,shortcutexecutionsothatthetargetmethoddoesnotactuallyexecute.

Unityenablesyoutospecifyandcustomizeanyinterceptionbehaviorandalsoenablesyoutouseinterceptionwithorwithoutacontainer.Theearlierapproachtopolicyinjectionisstillsupported,butyoucanalsoprovidepolicyinjectionbyusinginterceptionbehaviors.

ForinformationonusingbehaviorsseeBehaviorsforInterception.

Forinformationonusinginterceptionwithoutacontainerseethe"Stand-AloneUnityInterception"sectionintheUsingInterceptioninApplicationstopic.

Thistopiccontainsthefollowingsectionsthatdescribeusingpolicyinjection


andcontainerswithinterception:ProcessFlowforInterceptionUsingPolicyInjectionUsingtheBuilt-InPolicyInjectionBehaviorInterceptionPoliciesMatchingRulesCallHandlersandPolicyInjectionMoreInformation

ProcessFlowforInterceptionUsingPolicyInjection

UsingtheBuilt-InPolicyInjectionBehavior

InterceptionPolicies

MatchingRules

CallHandlersandPolicyInjection




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Interception and Policy Injection'%0AEntLib50_7a2c7fa6-28c2-479e-8df9-b4651824eb94%0APlease provide details of the error you have located...%0A


PolicyInjectionMatchingRules

UnityincludesmatchingruleimplementationsthatprovideawiderangeofcapabilitiesforselectingtheobjectsandtheirmemberstowhichUnitywilladdahandlerpipeline.Interceptionpoliciesusethematchingrulestodefinewhichmethodswillbeintercepted.

AmatchingruleisessentiallyapredicatethatUnitycheckseachtimeitinterceptsobjectcreation.IfallofthespecifiedmatchingrulesevaluatetoTrueforanyparticularinvocation,theapplicationblockwillcreateandaddthehandlerpipelineforthatpolicy.Ifanyoneofthematchingrulesdoesnotevaluatetotrue,Unitygeneratesaninstanceoftheoriginalobjectoraderivedobject,anddoesnotcreateaproxyorahandlerpipeline.

ThefollowingtableliststhematchingrulesprovidedwithUnity,andsummarizestheiruseandparameters.

Matchingrule Description

AssemblyMatchingRule

Selectsclassesinaspecifiedassembly.

CustomAttributeMatchingRule

Selectsclassesormembersthathaveanarbitraryattributeapplied.

MemberNameMatchingRule

Selectsclassmembersbasedonthemembername.

MethodSignatureMatchingRule

Selectsclassmethodsthathaveaspecificsignature.

NamespaceMatchingRule

Selectsclassesbasedonthenamespacename.

ParameterTypeMatchingRule

Selectsclassmembersbasedonthetypenameofaparameterforamemberofthetargetobject.

PropertyMatchingRule

Selectsclasspropertiesbynameandaccessortype.

ReturnType Selectsclassmembersthatreturnanobjectofthe

MatchingRule specifiedtype.

TagAttributeMatchingRule

SelectsclassmembersthatcarryaTagattributewiththespecifiedname.

TypeMatchingRule

Selectsclassesthatareofaspecifiedtype.

Thefollowingsectionsdescribethebuilt-inmatchingrulesindetail:TheAssemblyMatchingRuleTheCustomAttributeMatchingRuleTheMemberNameMatchingRuleTheMethodSignatureMatchingRuleTheNamespaceMatchingRuleTheParameterTypeMatchingRuleThePropertyMatchingRuleTheReturnTypeMatchingRuleTheTagAttributeMatchingRuleTheTypeMatchingRule

Youcanalsocreateandusecustommatchingrules.Formoreinformation,seeCreatingPolicyInjectionMatchingRules.Forinformationaboutusinginterception,seeUsingInterceptionandPolicyInjection.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Policy Injection Matching Rules'%0AEntLib50_412f3261-e0f5-4998-8373-5dc2ebda16af%0APlease provide details of the error you have located...%0A


TheAssemblyMatchingRule

Theassemblymatchingruleallowsdevelopers,operators,andadministratorstoselecttargetclassesbasedontheassemblynameorbyspecifyingareferencetoanassembly.

BehavioroftheAssemblyMatchingRule

CreatinganAssemblyMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Assembly Matching Rule'%0AEntLib50_4c47f30e-455d-4056-b773-69e6618c96fd%0APlease provide details of the error you have located...%0A


TheCustomAttributeMatchingRule

Thecustomattributematchingruleallowsdevelopers,operators,andadministratorstoselecttargetclassesbasedonacustomattributetypethatisappliedtoclassmembers.

BehavioroftheCustomAttributeMatchingRule

CreatingaCustomAttributeMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Custom Attribute Matching Rule'%0AEntLib50_e3c1e47a-2b21-4bff-8a1a-34f9191e4e65%0APlease provide details of the error you have located...%0A


TheMemberNameMatchingRule

Themembernamematchingruleallowsdevelopers,operators,andadministratorstoselecttargetclassesbasedonthenameoftheclassmembers(methodsorproperties),andallowsyoutousewildcardcharactersforthemembername.

BehavioroftheMemberNameMatchingRule

CreatingaMemberNameMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Member Name Matching Rule'%0AEntLib50_78c97c0f-62c4-4008-81c2-858b34e954cc%0APlease provide details of the error you have located...%0A


TheMethodSignatureMatchingRule

Themethodsignaturematchingruleallowsdevelopers,operators,andadministratorstoselecttargetclassesbasedonthenameandsignature(thelistofparametertypes)ofitsmembers.Thisruleallowstheuseofwildcardcharactersforthemembernames.

BehavioroftheMethodSignatureMatchingRule

CreatingaMethodSignatureMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Method Signature Matching Rule'%0AEntLib50_ebe602cf-d251-4bec-ad5c-d41bbef7550b%0APlease provide details of the error you have located...%0A


TheNamespaceMatchingRule

Thenamespacematchingruleallowsdevelopers,operators,andadministratorstoselecttargetclassesbasedontheirnamespace,usingwildcardcharactersforthechildnamespacenamesbutnotfortherootnamespacename.

BehavioroftheNamespaceMatchingRule

CreatingaNamespaceMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Namespace Matching Rule'%0AEntLib50_f5b9b0a8-66fd-4c47-b379-b49865ccc2c9%0APlease provide details of the error you have located...%0A


TheParameterTypeMatchingRule

Theparametertypematchingruleallowsdevelopers,operators,andadministratorstoselecttargetclassesbasedonthetypenameofaparameterforamemberofthetargetobject.

BehavioroftheParameterTypeMatchingRule

CreatingaParameterTypeMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Parameter Type Matching Rule'%0AEntLib50_ff549bb6-e05a-4ea9-82e8-11516e1eafea%0APlease provide details of the error you have located...%0A


ThePropertyMatchingRule

Thepropertymatchingruleallowsdevelopers,operators,andadministratorstoselectindividualpropertiesofthetargetclassesbasedontheirname,includingusingwildcardcharacters,andthecombinationofaccessorstheyimplement.

BehaviorofthePropertyMatchingRule

CreatingaPropertyMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Property Matching Rule'%0AEntLib50_07573c82-9f99-4474-8e16-d2b8b6ea62a8%0APlease provide details of the error you have located...%0A


TheReturnTypeMatchingRule

Thereturntypematchingruleallowsdevelopers,operators,andadministratorstoselecttargetclassesbasedonthetypeorthetypenameofthereturnvalue,usingwildcardcharactersifrequired.

BehavioroftheReturnTypeMatchingRule

CreatingaReturnTypeMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Return Type Matching Rule'%0AEntLib50_4b09e824-1e73-4230-988f-9a8ed8f5968a%0APlease provide details of the error you have located...%0A

CopyCode

CopyCode


TheTagAttributeMatchingRule

Thetagattributematchingruleallowsdevelopers,operators,andadministratorstoselecttargetclassesbasedonthenameofanattributeoftypeTagthatisappliedtoaclass,ortomembers(methodsorproperties)withinaclass.Forexample,thefollowingcodeshowsaclasswithtwotaggedmembers.C#

publicclassAnnotatedWithTags

{

[Tag("MyTagName")]

publicvoidTaggedMethod(stringparameter1)

{

...methodimplementationhere...

}

[Tag("AnotherTagName")]

publicstringTaggedProperty

{

...propertyimplementationhere...

}

}

VisualBasic

PublicClassAnnotatedWithTags

<Tag("MyTagName")>_

PublicSubTaggedMethod(parameter1AsString)

...methodimplementationhere...

EndSub

<Tag("AnotherTagName")>_

PublicPropertyTaggedPropertyAsString

CopyCode

CopyCode

...propertyimplementationhere...

EndProperty

EndClass

Thefollowingcodeshowsataggedclass.C#

[Tag("MyClassTagName")]

publicclassAnnotatedWithTagOnClass

{

...classimplementationhere...

}

VisualBasic

<Tag("MyClassTagName")>_

PublicClassAnnotatedWithTagOnClass

...classimplementationhere...

EndClass

BehavioroftheTagAttributeMatchingRule

CreatingaTagAttributeMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Tag Attribute Matching Rule'%0AEntLib50_fc17bbda-834f-4f22-88f3-ccbba75bd917%0APlease provide details of the error you have located...%0A


TheTypeMatchingRule

Thetypematchingruleallowsdevelopers,operators,andadministratorstospecifythetargetclassusingthenamespaceandclassnameofthetargettype.

BehavioroftheTypeMatchingRule

CreatingaTypeMatchingRuleatRunTimeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Type Matching Rule'%0AEntLib50_f745650b-dd5f-4703-be36-7b3ece55cb19%0APlease provide details of the error you have located...%0A


Attribute-DrivenPolicies

Acommonscenariowhenusinganypolicyinjectionframeworkistherequirementtospecifypoliciesforclassesandtheirmembersusingattributesdirectlyappliedtotheappropriateclassesandmembers.Unityinterceptionsupportsthistechnique—itactivelydiscoversclassesandmemberswithattributesthatdefinecallhandlersandappliestheappropriatepolicies.

Developersspecifyhandlersforclassesandtheirmembers(methodsandproperties)usingcallhandlerattributes.Eachattributeautomaticallyinstantiatestheappropriatecallhandler,andappliesthevaluesoftheattributeparameterstothepropertiesofthecallhandler.Usingdirectlyappliedattributeshasthefollowingadvantages:

DeveloperscanensurethatUnityaddshandlersthatarespecificallyrequiredinallcircumstancesandwhichshouldneverberemovedfromthehandlerpipeline.Developerscanfixthesettingsorvaluesofspecificparametersonclassesandclassmembers—forexample,bydefiningthatspecificparametervaluesmustalwaysbegreaterthanzeroorthatloggingwillalwaysoccurforspecificmethods.Developerscanpreventtheapplicationofahandlerpipelinetospecificmethodsandproperties,ortowholeclasses,usingtheApplyNoPoliciesAttributeattribute.

However,applyingpoliciesthroughattributesapplieddirectlytomembersofthetargetclassesmeansthatdevelopers,administrators,andoperatorscannolongercontrolthebehaviorofinterceptionwithoutchangingthesourcecodeandrecompilingthesolution.Inaddition,usingtheApplyNoPoliciesAttributeattributemaycauseunexpectedbehaviorfordevelopers,administrators,andoperators,whomayattempttoaddpoliciestoanapplicationwithoutbeingawareoftheappliedattributes.

PolicyandHandlerPrecedencewithAttributes

ExampleofanAttribute-DrivenPolicyToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Attribute-Driven Policies'%0AEntLib50_456aac54-4ba3-4904-adae-36fb5227fabc%0APlease provide details of the error you have located...%0A


EnterpriseLibraryCallHandlers

Thepatterns&practicesEnterpriseLibraryincludesasetofcallhandlersandtheequivalentcallhandlerattributesdesignedforusewiththeUnityPolicyInjectionBehavior.ThissectiondiscussessomeofthecommonscenariosforusingthePolicyInjectionApplicationBlockcallhandlers.Itexaminesthefollowingcommonscenarioswheretheblockcansimplifyandaccelerateapplicationdevelopment:

LoggingMethodInvocationandPropertyAccessHandlingExceptionsinaStructuredMannerValidatingParameterValuesAuthorizingMethodandPropertyRequestsMeasuringTargetMethodPerformance


LoggingMethodInvocationandPropertyAccess

HandlingExceptionsinaStructuredManner

ValidatingParameterValues

AuthorizingMethodandPropertyRequests

MeasuringTargetMethodPerformance




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Enterprise Library Call Handlers'%0AEntLib50_969b6f02-4da3-41d1-8527-c9e0009d1632%0APlease provide details of the error you have located...%0A


TheAuthorizationHandler

Theauthorizationhandlerprovidesthecapabilitytocheckthatthecurrentuser(thesecurityprincipalforthecurrentthread)hastherequisitepermissiontoaccesstheselectedobjectmethodorproperty.ThishandlerusestheSecurityApplicationBlockandtakesadvantageofthefeaturesthatitexposes.

Theauthorizationhandlerappliesthesecuritycheckbeforeinvocationoftheselectedmethodorsettingoftheselectedpropertyofthetargetobject.Ifthecurrentuserdoesnothavepermissiontoaccessthemethodorpropertyaccessor,theauthorizationhandlerabortsexecutionduringthepreprocessingstageanddoesnotinvokethetargetmethodorsetthetargetproperty.ItalsogeneratesanUnauthorizedAccessExceptionandpackagesitintothemessagepassedbacktotheprevioushandlerinthepipeline.

Note:ThiscallhandlerisimplementedintheMicrosoft.Practices.EnterpriseLibrary.Security.PolicyInjectionnamespaceoftheSecurityApplicationBlockintheMicrosoft.Practices.EnterpriseLibrary.Security.dllassembly.

BehavioroftheAuthorizationHandler

CreatingInstancesoftheAuthorizationHandler

UsingtheAuthorizationHandlerAttributeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Authorization Handler'%0AEntLib50_f27ca9a4-3284-4917-91b9-f2b8c73f24f0%0APlease provide details of the error you have located...%0A


TheExceptionHandlingHandler

Theexceptionhandlinghandlerprovidesthecapabilitytomanageandprocessexceptionsinastandardway.ThishandlerusestheExceptionHandlingApplicationBlock,takingadvantageofthewiderangeofoptionsthatitsupports.

Theexceptionhandlerappliesafterinvocationoftheselectedmethodoraccesstotheselectedpropertyofthetargetobject.Ifthemethodorpropertyaccessorraisesanexception,theexceptionhandlinghandlerwillinvokeanamedexceptionhandlingpolicydefinedwithintheExceptionHandlingApplicationBlock.Thispolicymayignoretheexception,returntheoriginalexception,orreplaceitwithanewexception.Theexceptionhandlinghandlerthenpackagestheexception(iftheExceptionHandlingApplicationBlockreturnsone)intothemessagepassedbacktotheprevioushandlerinthechain.

Eachinstanceoftheexceptionhandlinghandlermaintainsitsownhierarchyofexceptionpoliciesandanydependentobjects.WhenusingthelogginghandlerwiththeExceptionHandlingApplicationBlock,eachexceptionhandlinghandlerinstancewillcontainitsownLogWriterinstanceandsetofTraceListeners.IftheLoggingApplicationBlockisconfiguredtouseaflatfiletracelistenerorarollingflatfiletracelistener,youmayseemultiplelogfileswithGUIDsintheirfilenamesbecausemultipleinstancesofthetracelistenersarenotabletowritetotheconfiguredlogfileatthesametime.

Note:ThiscallhandlerisimplementedintheMicrosoft.Practices.EnterpriseLibrary.ExceptionHandling.PolicyInjectionnamespaceoftheExceptionHandlingApplicationBlockintheMicrosoft.Practices.EnterpriseLibrary.ExceptionHandling.dllassembly.

BehavioroftheExceptionHandlingHandler

CreatingInstancesoftheExceptionHandlingHandler

UsingtheExceptionHandlingHandlerAttributeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Exception Handling Handler'%0AEntLib50_d874dee7-1158-4cd7-900a-d592b5da5e69%0APlease provide details of the error you have located...%0A


TheLoggingHandler

Thelogginghandlerprovidesthecapabilitytowritelogmessagesandtracemessagesastheclientcodeinvokestheselectedmethodoraccessestheselectedpropertyofthetargetobject.ThishandlerusestheLoggingApplicationBlock,takingadvantageofthewiderangeoflogtypes,formatting,andtracingfeaturesthatitprovides.

Thelogginghandlerappliesbothbeforeandaftertheinvocationoftheselectedmethodoraccessingtheselectedpropertyofthetargetobject,dependingonsettingsintheapplicationconfiguration.

Note:ThiscallhandlerisimplementedinMicrosoft.Practices.EnterpriseLibrary.Logging.PolicyInjectionnamespaceoftheLoggingApplicationBlockintheassemblyMicrosoft.Practices.EnterpriseLibrary.Logging.dll.

ThelogginghandlerwillinitializetheLoggingApplicationBlockusingthesameconfigurationsourceasusedtocreatethelogginghandler.Bydefault,thiswillbethedefaultconfigurationsource.Itispossibletospecifyanalternativeconfigurationsourceifyouinstantiatethelogginghandleryourselfusingcode.Ifyoudothis,youshouldcreatetheconfigurationsourceonceandusethesameinstanceeachtimeyoucreatealogginghandlertopreventperformanceissuesandmemoryleaks.

Note:TheEnterpriseLibrary5.0ConfigurationtooldoesnotsupportEnvironmentalOverridesforthelogginghandlerCategories.Thismeansyouwillnotbeabletousetheconfigurationtoolsatdesigntimetocustomizetherun-timesettingsofyourlogginghandlerCategoriesconfigurationtosuitaparticularenvironmentsuchasatestorinstrumentationenvironment.

BehavioroftheLoggingHandler

CreatingInstancesoftheLoggingHandler

UsingtheLoggingHandlerAttributeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Logging Handler'%0AEntLib50_e7d4bacf-a864-4a50-b7c3-88acec5c4d7d%0APlease provide details of the error you have located...%0A


ThePerformanceCounterHandler

Theperformancecounterhandlerincrementsaspecificcountereachtimeitexecutesinresponsetoinvocationoftheselectedmethodorsettingoftheselectedproperty.ThishandlerusestheinstrumentationfeaturesthatarepartoftheEnterpriseLibraryCore.

Theperformancecounterhandlerappliesbothbeforeandafterinvocationoftheselectedmethodoraccesstotheselectedpropertyofthetargetobject.Thehandlercanincrementdifferenttypesofcountersandincrementmorethanonecountereachtime(suchasasingleinstanceandatotalcounter).

Note:ThiscallhandlerisimplementedintheMicrosoft.Practices.EnterpriseLibrary.PolicyInjection.CallHandlersnamespaceoftheMicrosoft.Practices.EnterpriseLibrary.PolicyInjection.dllassembly.

InstallingandRemovingPerformanceCounters

BehaviorofthePerformanceCounterHandler

CreatingInstancesofthePerformanceCounterHandler

UsingthePerformanceCounterHandlerAttributeToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Performance Counter Handler'%0AEntLib50_7f7053e1-9db6-433c-878f-b8a41b1d2a49%0APlease provide details of the error you have located...%0A


TheValidationHandler

Thevalidationhandlerprovidesthecapabilitytotestwhetherthevalueprovidedfortheselectedproperty,orthevaluesspecifiedfortheparametersoftheselectedmethod,arevalidagainstspecificrules.ThishandlerusestheValidationApplicationBlock,takingadvantageofthewiderangeofcapabilitiesthatitoffers.

Thevalidationhandlerappliesthevalidationbeforeinvokingthemethodorsettingthepropertyofthetargetobject.Ifvalidationfails,thevalidationhandlerabortsexecutionofthepreprocessinghandlerpipeline,doesnotinvokethemethodorsettheproperty,andraisesanArgumentValidationException.

Note:ThiscallhandlerisimplementedinMicrosoft.Practices.EnterpriseLibrary.Validation.PolicyInjectionnamespaceoftheValidationApplicationBlock,intheassemblyMicrosoft.Practices.EnterpriseLibrary.Validation.dll.

BehavioroftheValidationHandler

CreatingInstancesoftheValidationHandler

UsingtheValidationHandlerAttribute




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'The Validation Handler'%0AEntLib50_ad452cb9-20c7-4db2-9801-73417714f46c%0APlease provide details of the error you have located...%0A


DesignofUnity

Thistopicdescribesthedesigngoals,thearchitecture,andthedesignhighlightsofUnity.YoudonothavetounderstandthedesigntouseUnity;however,thistopicwillhelpyoutounderstandhowitworksandhowitinteractswiththeunderlyingObjectBuildersubsystem.

DesignGoals




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Design of Unity'%0AEntLib50_d07ea269-a63f-4817-8dd0-10019c9914b4%0APlease provide details of the error you have located...%0A


ExtendingandModifyingUnity

Ifrequired,youcanextendandmodifyUnitytobettersuityourownrequirements.YoucanextendUnitybydoingthefollowing:

CreatingLifetimeManagersthatcontrolhowandwhenthecontainerwilldisposeofinstancesofobjectsitresolves.CreatingandUsingContainerExtensionsthatcanchangethebehaviorofthecontainer,theinstancegenerationmechanism,andthedependencyinjectionandinterceptionfeatures.CreatingPolicyInjectionMatchingRulesthatprovidesalternativetechniquesforselectingclassesandclassmemberstowhichUnitywillattachahandlerpipeline.CreatingInterceptionPolicyInjectionCallHandlersthatperformthetask-specificprocessingyourequireformethodinvocationsandpropertyaccessors.CreatingInterceptionHandlerAttributesthatcauseUnitytoaddbuilt-inorcustomcallhandlerstothehandlerpipeline.Ifyoucreateacustomhandler,youmayalsowanttocreateacustomattributethatdeveloperscanusetoapplyyourhandlerbyaddingtheattributedirectlytoclassesorclassmemberswithinthesourcecodeofanapplication.CreatingInterceptionBehaviorsthatdescribewhattodowhenanobjectisintercepted.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Extending and Modifying Unity'%0AEntLib50_13f11174-8fd1-4406-8bc7-9da9c762811d%0APlease provide details of the error you have located...%0A


CreatingLifetimeManagers

Unitysupportsseveralapproachesforregisteringclasses,interfaces,andinstancesofexistingobjects.YoucanusetheRegisterTypeandRegisterInstancemethodstoregisterobjectinstancesatruntime,orspecifythemappingsandregistrationsatdesigntimeinconfiguration.YoucanalsospecifyalifetimemanagerwithalloftheseapproachesthatwillcontrolhowUnityresolvesinstancesofthespecifiedtypesandhowitholdsreferencestotheseinstances.Thebuilt-inlifetimemanagersallowyoutospecifyobjectsassingletons,withweakreferences,orasper-threadinstances.Formoredetails,seeUnderstandingLifetimeManagers.

YoucancreatecustomLifetimeManagerclassesifyourequireadditionalfunctionalitynotavailableinthedefaultlifetimemanagers.DocumentationtohelpyoudothisisavailablefromtheUnityCommunityWebsiteonCodePlex.





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Lifetime Managers'%0AEntLib50_35ea2347-02e3-4d6a-a787-cd3bc7f89538%0APlease provide details of the error you have located...%0A


CreatingandUsingContainerExtensions

YoucancreateyourowncustomUnitycontainerextensions,orusecontainerextensionscreatedbythirdpartieswithUnity.Unityusesdefaultcontainerextensionstoimplementitsownfunctionality.Forexample,theinterceptionmechanismprovidedbyUnityisimplementedasacontainerextension.

DocumentationtohelpyouunderstandObjectBuilder,andthestepsrequiredtocreatecustomcontainerextensions,isavailablefromtheUnityCommunityWebsiteonCodePlex.





mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating and Using Container Extensions'%0AEntLib50_d2dab81f-3acb-40ba-8fe5-5253e948e6fa%0APlease provide details of the error you have located...%0A

CopyCode

CopyCode


CreatingPolicyInjectionMatchingRules

UnitydefinesaninterfacenamedIMatchingRule,whichallclassesthatimplementmatchingrulesmustimplement.ThisinterfacedeclaresasinglemethodnamedMatchesthattakesaMethodBaseinstanceandreturnsaBooleanvalue.C#

publicinterfaceIMatchingRule

{

boolMatches(MethodBasemember);

}

VisualBasic

PublicInterfaceIMatchingRule

FunctionMatches(ByValmemberAsMethodBase)AsBoolean

EndInterface

Insideaconcreteimplementationofthisinterface,acustommatchingruleclasscanaccessdetailsofthecurrentmember(methodorproperty)ofthetargetobjectanddeterminewhetherUnityshouldaddahandlerpipelinetothismember.TheMatchesmethodshouldreturnTrueifthecurrentmembermatchestherequirementsofthismatchingrule;ifthecurrentmemberdoesnotmatchtherequirementsofthismatchingrule,itshouldreturnFalse.

Note:Rememberthattheremaybeseveralmatchingrulesdefinedforapolicy,andeveryonemustreturnTruewhenUnitycallstheirMatchesmethodinorderforUnitytoaddthehandlerpipelinetothetargetclassmember.

Example:TheTagAttributeMatchingRuleToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Policy Injection Matching Rules'%0AEntLib50_17137b99-e7a8-4944-b784-87db6ab429af%0APlease provide details of the error you have located...%0A


CreatingInterceptionPolicyInjectionCallHandlers

Tocreateacallhandlerforpolicyinjection,youmustunderstandthewaythatUnitypassescallsthroughthepolicypipeline.Thistopicexplainshowthepipelineexecutescallhandlers,andhowitcanblockorabortexecutionwhenanerroroccurs,orondemand(suchaswhenavalidationhandlerdetectsavalidationerrororanauthorizationhandlerdetectsanunauthorizeduser).Thistopiccontainsthefollowingsections:

TheICallHandlerInterfaceandPipelineExecutionOutlineImplementationofaCallHandlerExceptionsandAbortedPipelineExecution

TheICallHandlerInterfaceandPipelineExecution

OutlineImplementationofaCallHandler

ExceptionsandAbortedPipelineExecutionToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Interception Policy Injection Call Handlers'%0AEntLib50_587afe3d-d6c7-447f-bb9b-8fd750174bcc%0APlease provide details of the error you have located...%0A


CreatingInterceptionHandlerAttributes

Handlerattributesallowdeveloperstoapplyhandlerstoclassesandclassmembersdirectly,withoutconfiguringthemintheapplicationconfigurationfile.Developerscreatingcustomhandlersmaywanttoprovideanattributefortheirhandlers.Tobuildacustomhandlerattribute,youcreateaclassthatderivesfromtheHandlerAttributebaseclassshownhere.C#

publicabstractclassHandlerAttribute:Attribute

{

///Derivedclassesimplementthismethod.Whencalled,itcreatesa

///newcallhandlerasspecifiedintheattributeconfiguration.

///Theparameter"container"specifiestheIUnityContainer

///tousewhencreatinghandlers,ifnecessary.

///returnsanewcallhandlerobject.

publicabstractICallHandlerCreateHandler(IUnityContainercontainer);

privateintexecutionorder;

///<summary>

///Getsorsetstheorderinwhichthehandlerwillbeexecuted.

///</summary>

publicintOrder

{

get{returnthis.executionorder;}

set{this.order=value;}

}

}

VisualBasic

PublicMustInheritClassHandlerAttribute:InheritsAttribute

'''Derivedclassesimplementthismethod.Whencalled,itcreatesa

'''newcallhandlerasspecifiedintheattributeconfiguration.

'''TheparametercontainerspecifiestheIUnityContainer

'''tousewhencreatinghandlers,ifnecessary.

'''Returnsanewcallhandlerobject.

PublicMustOverrideFunctionCreateHandler(containerAsIUnityContainer)AsICallHandler

PrivateexecutionorderAsInteger

'''<summary>

'''Getsorsetstheorderinwhichthehandlerwillbeexecuted.

'''</summary>

PublicPropertyOrderAsInteger

Get

ReturnMe.executionorder

EndGet

Set

Me.order=value

EndSet

EndProperty

EndClass

Inyourcustomattributeclass,youmustimplementoneormoreconstructorsthatacceptvaluesfromtheattribute,and/orimplementnamedpropertiesthatthedevelopercanusetosetthepropertiesoftheclass.ThenyousimplyoverridetheCreateHandlerabstractmethoddeclaredwithinthebaseclasstocreateandreturntherequiredhandlerclassasanICallHandlerinstance.

ExampleCallHandlerAttributeAsanexample,youcouldcreateacallhandlerattributeforacallhandlersimilartothatdescribedinthetopicCreatingInterceptionPolicyInjectionCallHandlersthatpreventsinvocationofbusinessprocessesonweekenddays.Inthiscase,assumethatthehandlerhasapropertynamedSaturdayOKthatallowsyoutosetittoallowcallstooccuronaSaturday.Thecallhandlerhastwoconstructors:onethattakesaparameterthatsetsthevalueoftheSaturdayOKpropertytothespecifiedvalue(trueorfalse),andonethattakesnoparametersandsetsthedefaultvalue(false)fortheSaturdayOKproperty.ThefollowingcodeshowsanimplementationoftheWeekdayOnlyCallHandlerAttribute.C#

[AttributeUsage(AttributeTargets.Class|AttributeTargets.Property|AttributeTargets.Method)]

publicclassWeekdayOnlyCallHandlerAttribute:HandlerAttribute

{

privateboolallowSaturday;

publicWeekdayOnlyCallHandlerAttribute()

{

allowSaturday=false;

}

publicWeekdayOnlyCallHandlerAttribute(boolSaturdayOK)

{

allowSaturday=SaturdayOK;

}

publicoverrideICallHandlerCreateHandler(IUnityContainerignored)

{

returnnewWeekdayOnlyCallHandler(allowSaturday,Order);

}

}

VisualBasic

<AttributeUsage(AttributeTargets.ClassOrAttributeTargets.PropertyOrAttributeTargets.Method)>_

PublicClassWeekdayOnlyCallHandlerAttribute:InheritsHandlerAttribute

PrivateallowSaturdayAsBoolean

PublicSubNew()

allowSaturday=False

EndSub

PublicSubNew(SaturdayOKAsBoolean)

allowSaturday=SaturdayOK

EndSub

PublicOverridesFunctionCreateHandler(ignoredAsIUnityContainer)AsICallHandler

ReturnNewWeekdayOnlyCallHandler(allowSaturday,Order)

EndFunction

EndClass

NoticetheAttributeUsageattributethatspecifieswheredeveloperscanapplythenewcustomattribute(onaclass,aproperty,oramethod),and—inthiscase—theprovisionoftwoconstructors.Thefirst(default)constructorusesthedefaultvalue(false),whilethesecondacceptsavaluefortheSaturdayOKproperty.TheCreateHandlermethodoverrideinstantiatestheWeekdayOnlyCallHandlerclasswiththeappropriatevaluesandreturnsthisasanICallHandlerreference.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Interception Handler Attributes'%0AEntLib50_f9822e7e-003d-482d-9d72-5f795704367a%0APlease provide details of the error you have located...%0A


CreatingInterceptionBehaviors

UnityusestheInterceptorclasstospecifyhowinterceptionhappens,andtheInterceptionBehaviorclasstodescribewhattodowhenanobjectisintercepted.Unityinterceptionutilizesabehaviorpipelinetoforthebehaviors.TheInterceptionBehaviorPipelinemaintainsalistofinterceptionbehaviorsandmanagesthem,callingthemintheproperorderwiththecorrectinputs.

ForinformationonthedetailsaboutinterceptionbehaviorsseeInterceptionwithUnityandBehaviorsforInterception.




mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Creating Interception Behaviors'%0AEntLib50_d2ef0985-d33a-422c-b202-b0f47dfa316e%0APlease provide details of the error you have located...%0A



WhenyouuseUnityinyourapplications,youmustdeploytherequiredassemblieswithyourapplicationorinstalltheassembliesonthetargetcomputerintheglobalassemblycache(GAC).YoumustincludetheassemblynamedMicrosoft.Practices.Unity.dll.Ifyouareusinginterception,youwillalsorequiretheassemblynamedMicrosoft.Practices.Unity.Interception.dll.

YoucandeployanapplicationthatusesUnityinoneoftwoconfigurations:AsprivateassembliesintheapplicationfolderhierarchyAssharedassembliesinanyfilesystemlocationorintheglobalassemblycache

ForadviceonusingUnitywithapplicationsthatruninpartialtrustmodes,seeUsingUnityinPartialTrustEnvironments.

ForadviceonupdatingexistingversionsofUnityassemblies,seeUpdatingtheUnityAssemblies.

WhenyoucompiletheinstalledversionofUnitysourcecode,theassembliesproducedwillnotbestrongnamed.Asaresult,theycannotbeinstalledintheglobalassemblycache,norwilltheyhavetheotherbenefitsassociatedwithstrong-namedassemblies.TolearnhowtostrongnameUnityassemblies,seeStrongNamingtheUnityAssemblies.

Note:Unitythrows(andhandlesinternally)LockSynchronizationexceptions.LockSynchronizationexceptionsmaybeobservedinthedebuggeroutputbuttheyarehandledinternallyandnoactionisrequired.

UsingXCopy

UsingtheGlobalAssemblyCache


VersioningToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].


http://msdn2.microsoft.com/en-us/library/wd40t7ad(vs.71).aspx



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Deployment and Operations'%0AEntLib50_11c11eec-a77e-4060-b08b-77e389d1a916%0APlease provide details of the error you have located...%0A


UsingUnityinPartialTrustEnvironments

Unityusesdynamicallygeneratedmethodstoperforminjection,andthe.NETFrameworksecuritymodelimposessomesecuritylimitationsthatyoushouldbeawareofifyouwanttouseUnityinapplicationsthatwillruninlessthanfulltrustenvironments.ThelimitationwhenusingUnityinapartialtrustenvironmentisthatyoucannotregisterandusemappingsusingtheRegisterTypemethodswherethetargetclassisinternal(C#),Friend(VisualBasic.NET),private(C#),orPrivate(VisualBasic.NET).

FormoreinformationaboutsecurityissueswhenusingdynamicallygeneratedMicrosoftintermediatelanguage(MSIL)code,seeSecurityIssuesinReflectionEmitfor.NET3.5andSecurityIssuesinReflectionEmitfor.NET2.0.



http://msdn2.microsoft.com/en-us/library/9syytdak.aspx

http://msdn2.microsoft.com/en-us/library/9syytdak(VS.80).aspx


mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Using Unity in Partial Trust Environments'%0AEntLib50_d76a8dac-cfa3-4884-8156-14d96324f732%0APlease provide details of the error you have located...%0A


UpdatingtheUnityAssemblies

IfanupgradedversionofUnitybecomesavailable,youcaninstallthenewversionandhaveallapplicationsusetheupdatedassembly.However,ifthenewversionintroducescompatibilityproblemsforcertainapplications,youcaninstallthenewversionintheglobalassemblycacheandconfiguresomeapplicationstousetheupdatedversion,whileotherscontinuetousetheearlierversion.

UpdatingPrivateAssemblies

UpdatingSharedAssembliesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Updating the Unity Assemblies'%0AEntLib50_935dd061-fa01-4f9b-a330-1a89e3397346%0APlease provide details of the error you have located...%0A


StrongNamingtheUnityAssemblies

IfyoubuildUnityfromthesourcecode,youmaydecidetoapplystrongnamingtotheassemblies.Astrongnameconsistsoftheassembly'sidentity—thesimpletextname,versionnumber,andcultureinformation(ifprovided)—plusapublickeyandadigitalsignature.Thestrongnameisgeneratedfromanassemblyfile(thefilethatcontainstheassemblymanifest,whichinturncontainsthenamesandhashesofallthefilesthatmakeuptheassembly),usingthecorrespondingprivatekey.Signinganassemblywithastrongnameensuresthatitsnameisgloballyunique.Assemblieswiththesamestrongnameareexpectedtobeidentical.

Forexample,ifyouintendtoshareUnityassembliesamongseveralapplications,youcaninstallthemintotheglobalassemblycache.Eachassemblyintheglobalassemblycachemusthaveagloballyuniquename.Youcanuseastrongnametoensurethis.Evenifyouonlyusetheassemblieswithinasingleapplication,youcanstrongnametheassembliestoensurethatyourapplicationusesthecorrectversionoftheassemblies.

Strongnamessatisfythefollowingrequirements:Strongnamesguaranteenameuniquenessbyrelyingonuniquekeypairs.Noonecangeneratethesameassemblynamethatyoucanbecauseanassemblygeneratedwithoneprivatekeyhasadifferentnamethananassemblygeneratedwithanotherprivatekey.Strongnamesprotecttheversionlineageofanassembly.Astrongnamecanensurethatnoonecanproduceasubsequentversionofyourassembly.Userscanbesurethataversionoftheassemblytheyareloadingcomesfromthesamepublisherthatcreatedtheversionoriginallyprovidedwiththeapplication.Strongnamesprovideastrongintegritycheck.Passingthe.NETFrameworksecuritychecksguaranteesthatthecontentsoftheassemblyhavenotbeenchangedsinceitwasbuilt.However,notethatstrongnamesthemselvesdonotimplyaleveloftrustsuchasthelevelprovidedby,forexample,adigitalsignatureandsupportingcertificate.

Forinformationaboutdeployingassembliesintotheglobalassemblycache,seeWorkingwithAssembliesandtheGlobalAssemblyCache.

http://msdn2.microsoft.com/en-us/library/6axd4fx6.aspx

UsingVisualStudiotoStrongNametheUnityAssembliesToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Strong Naming the Unity Assemblies'%0AEntLib50_bb0e725c-8c94-4355-b26f-d59998cee743%0APlease provide details of the error you have located...%0A


UnityQuickStarts

TheinstructionsinthisQuickStarttopicaredirectedattheSilverlightsolution.Thoughtherearemanysimilarities,someinstructionsinthistopic,suchasreferencestoProgram.csorProgram.vb,donotapplytotheSilverlightproject.ThefollowingQuickStartapplicationsdemonstratesomeofthekeyfeaturesofUnity:

Walkthrough:TheUnityStopLightQuickStart.ThisQuickStartdemonstratesdependencyinjectiontechniques.ThisistheonlyQuickStartprojectintheSilverlightsolution.Walkthrough:TheUnityEventBrokerExtensionQuickStart.ThisQuickStartprovidesanexampleextensionfortheUnitycontainer.TheSilverlightsolutiondoesnoincludetheEventBrokerQuickStart.

Note:UnityQuickStartsareonlyavailableifyouinstallthestandaloneUnityMSI.TheUnityMSIisavailableatpatterns&practices-UnityonCodePlex.

http://unity.codeplex.com/Project/ProjectRss.aspx?ProjectRSSFeed=codeplex://sourcecontrol/unity

BuildingtheQuickStartsToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Unity QuickStarts'%0AEntLib50_d01aa11a-d50d-401c-8936-839432eb9df8%0APlease provide details of the error you have located...%0A


Walkthrough:TheUnityStopLightQuickStart

TheStopLightQuickStartdemonstratesthewaysthatyoucanuseUnityandtheUnitycontainerinyourapplications.TheuserinterfaceisasimpleWindowsFormsapplicationthatdisplaysthethreecolorsofastoplightortrafficlight—itshowsred,yellow,andgreen,inturn,forspecifiedperiods.Youcanconfigurethedisplayperiodsforeachcolor.Thefollowingillustrationshowstheuserinterface.

TheStopLightQuickStartdemonstratesthefollowingfeaturesofUnity:RegisteringmappingsfortypeswiththecontainerImplementingtheModelViewPresenterpatternbyinjectingapresenterintotheuserinterfaceInjectingabusinesscomponentintoobjectsusingproperty(setter)injectionImplementingaconfigurablepluggablearchitecture

ThefollowingdiagramshowstheclassesandarchitectureoftheStopLightQuickStartapplication.

RegisteringMappingsforTypeswiththeContainer

ImplementingtheModel-View-PresenterPattern

InjectingaBusinessComponentusingProperty(Setter)Injection

ImplementingaConfigurablePluggableArchitectureToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Walkthrough: The Unity StopLight QuickStart'%0AEntLib50_8de96653-280c-450c-b8e8-543066c623a5%0APlease provide details of the error you have located...%0A


Walkthrough:TheUnityEventBrokerExtensionQuickStart

TheEventBrokerExtensionQuickStartdemonstrateshowyoucanextendtheUnitycontainerbyaddingacustomextension.TheQuickStartimplementsaneventbrokerforthecontainerasacontainerextensionanddemonstratesthenewextensionusingtheStopLightapplicationdiscussedinWalkthrough:TheUnityStopLightQuickStart.

TheEventBrokerExtensionQuickStartcontainsfiveprojects:SimpleEventBroker.Thisprojectimplementsasimplepublishandsubscribemechanismthatsupportsmultipleeventpublishersandmultiplesubscribers.EventBrokerExtension.Thisprojectimplementsthecustomcontainerextensionthatallowsapplicationstopublishandsubscribetoeventsusingattributesorexplicitlyusingcode.StopLight.ThisprojectisbasicallythesameasthatdescribedintheUnityStopLightQuickStart,butitusesthecustomcontainerextensiontomanagethepublishingof,andsubscriptionto,twoeventswithintheapplication.Tests.EventBrokerExtension.AtestfixturefortheEventBrokerExtension.Tests.SimpleEventBroker.AtestfixturefortheSimpleEventBroker.

Forinformationabouthowyoucancreateandusecustomcontainerextensions,seeCreatingandUsingContainerExtensions.

ThefollowingdiagramshowstheclassesandarchitectureoftheEventBrokerExtensionQuickStart.

IfyoucomparethisdiagramtothestructureoftheStopLightQuickStartshowninWalkthrough:TheUnityStopLightQuickStart,youcanseethattheEventBrokerExtensionQuickStarthasthefollowingadditionalfeatures:

TheProgramclass,whichregistersthetypemappingsinthecontainerandcallstheResolvemethodtoinstantiatethemainStopLightform,alsoaddstheSimpleEventBrokerExtensiontothecontainer.TheSimpleEventBrokerExtension,whichinheritsfromtheUnityContainerExtensionbaseclass,createsaninstanceoftheEventBrokerclassthatimplementsthepublishandsubscribepatternfordistributedevents.TheEventBrokerclasscreatesaninstanceofthePublishedEventclassthatprovidesthefacilitiesformaintainingalistofeventsubscriptionsandraisingeventstoregisteredsubscribers.TheStopLightPresenter,StopLightSchedule,andRealTimeTimerclassesincludeattributesthatregistereventpublicationsandsubscriptionswiththeSimpleEventBrokerExtensionclass.

TheEventBrokerExtensionQuickStartdemonstratesthefollowingfeaturesofUnityandthecustomcontainerextensionmechanism:

CreatingthecustomUnitycontainerextensionAddinganextensiontotheUnitycontaineratruntimeUsingtheexampleEventBrokerExtension

CreatingaCustomUnityContainerExtension

AddinganExtensiontotheUnityContaineratRunTime

UsingtheExampleEventBrokerExtensionToprovidefeedback,getassistance,ordownloadadditionalcontent,pleasevisittheEnterpriseLibraryCommunityWebsite.Toreportdocumentationerrorsorprovidefeedbackonthisdocumentation,[email protected].



mailto:[email protected]?Subject=EntLib 5.0 Documentation Feedback&Body=Topic: 'Walkthrough: The Unity Event Broker Extension QuickStart'%0AEntLib50_7b1ead79-2418-4b48-8630-e152a3a0a60e%0APlease provide details of the error you have located...%0A

Documents

Microsoft Enterprise Library 5 - Documentation & Helpacross different layers of their applications. Unity Dependency Injection and Interception. Developers can use this to implement